DBC 反应组件

DBC项目中可再使用的再使用组件.

这个库提供了一个共享的,可主题的组件系统,用于整个DBC的内部(和选定的外部)应用程序. 其目的是促进一致性,加快发展,提高整体质量和无障碍性.

图书馆的目的

本组成部分图书馆的目标是:

• 一致性
  对DBC的数字产品,特别是内部工具,提供统一的外观和感觉.

• 开发速度
  通过重新使用经过良好检验的部件来减少开发和维护时间,而不是从零开始重建UI.

• 质量和可获取性
  组成部分根据最佳做法进行审查和建设,同时考虑到无障碍性和稳健性,确保良好的基线质量.

• 减少第三方依赖性
  通过在整个组织建立和共享我们自己的组成部分,减少对外部国家预防机制一揽子计划的依赖,增加数字独立性.

开始

(1) 安装软件包

npm install @dbcdk/react-components

(2) 导入全局样式

重要内容: 组件库需要全局样式在您的应用程序中导入一次 .

import '@dbcdk/react-components/themes/dbc.css'

(3) 添加 ThemeScript 在根布局中( 下一步. js 示例)

图书馆共享的 CSS 基础仍然正常导入, 但是 产品主题切换由 ThemeScript + 键 useTheme()。 。 。 . ThemeScript 恢复持续颜色方案和产品主题 颜料,因此该应用程序避免了第一个负载上错误主题的闪光.

import { ReactNode } from 'react'

import { ThemeScript } from '@dbcdk/react-components'
import { TooltipProvider } from '@dbcdk/react-components/client'
import '@dbcdk/react-components/themes/dbc.css'

export default function RootLayout({ children }: Readonly<{ children: ReactNode }>) {
  return (
    <html lang="da" suppressHydrationWarning>
      <head>
        <ThemeScript defaultTheme="dbc" />
      </head>
      <body>
        <TooltipProvider>{children}</TooltipProvider>
      </body>
    </html>
  )
}

4) 应用程序中切换主题

使用示例 useTheme() 当您想要控制主题时 :

'use client'

import { AppHeader, Button, useTheme } from '@dbcdk/react-components/client'
import { Moon, Sun } from 'lucide-react'

export default function Header() {
  const { theme, switchTheme } = useTheme({ defaultTheme: 'dbc' })

  return (
    <AppHeader>
      <Button
        variant="outlined"
        onClick={() => switchTheme(theme === 'dbc' ? 'filmstriben' : 'dbc')}
      >
        {theme === 'dbc' ? <Moon /> : <Sun />}
      </Button>
    </AppHeader>
  )
}

光是默认的颜色方案,包括水合前. ThemeScript, (中文(简体) ), useColorScheme()或系统 偏好。 明确默认OS偏好,使用 <ThemeScript defaultColorScheme="system" /> 财务报告和审定财务报表 useColorScheme('system')。 。 。 .

钩子更新 data-product-theme,应用选定的产品主题 符号覆盖,并坚持选择.

如果您只需要读取活动主题状态, 请使用 useGetActiveTheme() 改为 useTheme()数字 :

'use client'

import { useGetActiveTheme } from '@dbcdk/react-components/client'

export function ThemeBadge() {
  const { theme, colorScheme, themeKey } = useGetActiveTheme()

  return <span>{themeKey ?? `${theme} / ${colorScheme}`}</span>
}

useGetActiveTheme() 故意只读。 报告当前 活动主题状态 ThemeScript或 另一个挂载的主题控件 . themeKey 仅在两者同时设置时 theme 财务报告和审定财务报表 colorScheme 解决,否则 null如果你的应用通过一个 自定义 storageKey编号 :colorSchemeStorageKey (见下文),通过同样的价值观 在这里,它读到正确的持续状态.

5)在同一来源上运行多个应用程序

useTheme, (中文(简体) ), useColorScheme, (中文(简体) ), useGetActiveTheme, (中文(简体) ), ThemeScript, (中文(简体) ), ThemeButton编号 :ThemeMenuSection,以及 ColorSchemeButton编号 :ColorSchemeMenuSection 都坚持饼干+ localStorage 在共享默认密钥下。 如果两个 在这个库上构建的不同应用程序运行于同一来源( 例如 2) 将阅读并覆盖彼此的主题 默认选择.

为了保持它们的独立性,通过 storageKey (产品) 专题)和/或 colorSchemeStorageKey (彩色计划, ThemeScript 仅 -- 其他地方,这是 storageKey 选项 useColorScheme:

<ThemeScript
  defaultTheme="dbc"
  storageKey="my-app-theme"
  colorSchemeStorageKey="my-app-color-scheme"
/>

const { theme, switchTheme } = useTheme({ defaultTheme: 'dbc', storageKey: 'my-app-theme' })
const { colorScheme, switchColorScheme } = useColorScheme(undefined, {
  storageKey: 'my-app-color-scheme',
})

在给定的应用程序中, 在任何地方使用相同的密钥( O)ThemeScript钩子和 ),或数值将不一致地解决.

软件包集成

软件包的目标为捆绑机(Next.js,Vite,webpack)和带有CSS变换的测试跑车 (Vites,带有CSS模块映射器的Jest). 每个入口 - 主入口, /client, (中文(简体) ), /tanstack, (中文(简体) ), /tanstack-virtual 财务报告和审定财务报表 /markdown - 进口CSS模块和未捆绑的文件 与无延伸的相对进口, 所以节点自己的 import编号 :require 无法直接装入.

可选表格集成

Table 财务报告和审定财务报表 useTableData 可从 @dbcdk/react-components/client 没有坦斯塔克。 传出同样的 ColumnItem<T>[] 到桌子和钩子 sorting.columns; 钩子使用每列 accessor 和可选 sortFunction栏 id 作为 sortBy。 。 。 .

现有存取器形状的列( E)accessorKey 编号 : accessorFn),包括类型 TanStack 列, 也不引入 TanStack 依赖性 成为核心宣言。 明确 columnComparators 覆盖出列排序 .

useTableSettings, (中文(简体) ), TableSettings,以及 TableSettingsMenuSection 也为 可从 /client,及其类型和 localStorageTableSettingsStorage他们接受普通表格的列和 荣誉 hidden 财务报告和审定财务报表 canHide。现有的 TanStack 列带有: accessorKey, (中文(简体) ), meta.hidden,以及 enableHiding 保持兼容性.

安装 @tanstack/react-table 页:1 TanstackTable 从 /tanstack现有 设置导出自 /tanstack 继续作为相容性别名.

可选的马克下集成

MarkdownEditor 财务报告和审定财务报表 MarkdownViewer 可从 @dbcdk/react-components/markdown,而不是从主条目或 /client他们 需求 markdown-it,这是一个可选的对等关系:安装 (单位:千美元)npm i markdown-it只有你使用它们. MarkdownViewer 同时在 服务器组件; MarkdownEditor 是客户端组件.

下一个.js 配置

添加 transpilePackages: ['@dbcdk/react-components'] 到您的下一个.js配置 因此,它处理库的 CSS 模块。 导入交互式组件和 来自 /client。包装集成检查涵盖下一个.js 16.2.6 有网络包装和19.2.4反应.

使用故事书

故事书是这个图书馆的主要文献和探索工具.

本地故事书

npm run storybook

故事书运行 http://localhost:6006。 。 。 .

在故事书中你可以:

1. 在左手导航中浏览组件
2. 打开一个故事来查看变体和状态
3. 调整道具通过 控件
4. 阅读准则和使用说明 文档 选项卡

主题

使用 \\ \ \ \ 主题选择器 用于在可用主题(例如光和暗)之间切换.

所有组件都使用主题文件中定义的CSS变量来进行样式.

无障碍(a11y)

无障碍是这个图书馆的头等大事.

我们的目标是确保各组成部分:

• 可用键盘导航
• 具有明显和一致的重点状态
• 与屏幕阅读器合作
• 遵循共同的ARIA和语义HTML最佳做法

故事书包括a11y addon,以帮助识别开发过程中的问题.

MIME 类型助手

这些助手在服务器和客户端上工作,从根导出 /client 切入点:

import { formatMimeType, getMimeTypeExtension } from '@dbcdk/react-components'

formatMimeType('application/pdf') // 'PDF'
formatMimeType('text/plain; charset=utf-8') // 'Tekst'
getMimeTypeExtension('image/jpeg') // 'jpg'

formatMimeType 为常见的 MIME 类型提供丹麦标签,保留未知值不变,并返回 - 页:1 null 或者说 undefined。 。 。 . getMimeTypeExtension 返回没有常见图像类型和 PDF 的扩展名,或 undefined 用于不支持的类型。 在查找已知类型时,两者都忽略了MIME参数,外壳和周围的白空间.

本地选择控制

使用 NativeSelect 当你想要浏览器的本地 <select> 互动, 包括电话上的取站台. Select 是自定义的弹出控制. 从客户端入口导入交互式窗体控制 :

'use client'

import { useState } from 'react'
import { NativeSelect } from '@dbcdk/react-components/client'

export function FormatFilter() {
  const [format, setFormat] = useState('')

  return (
    <NativeSelect
      label="Format"
      name="format"
      options={[
        { label: 'Alle formater', value: '' },
        { label: 'PDF', value: 'pdf' },
      ]}
      selectedValue={format}
      onChange={setFormat}
    />
  )
}

NativeSelect 包含 InputContainer: 通过 labelAction, (中文(简体) ), helpText, (中文(简体) ), error, (中文(简体) ), orientation,或 fullWidth 直接而不是添加另一个标签包装. 它被控制并且是单选的 : onChange 接收原始选项值 (字符串、数字或对象 datakey),不是DOM事件. 提供的选项 value: '' 是一个真正的选择,并替换合成占位符。 否则, 选择引用的占位符 onClear,当提供.

原生属性和元素 ref 被转发,包括 name, (中文(简体) ), form, (中文(简体) ), required, (中文(简体) ), disabled,以及 onBlur。参加 FormData, (中文(简体) ), 财务报告和审定财务报表 required 使用浏览器验证. allowClearWhenRequired 允许清除 但不能绕过验证 使用 MultiSelect 用于多个选择.

默认的中文本使用16px主题符号. 粗指头至少会 44px控制高音符,而小/中文本则使用16px符号. 这个 保持移动控件的可读性,而不取代本地交互. 检查 在验证时, 出版了关于 iOS Safari 和 Android Chrome 的 故事集 平台拾取者行为;桌面仿真不验证这些拾取者.

捐款

见 CONTRIBUTING.md 详细指南:

• 文件夹结构
• 造型和主题规则
• 故事书要求
• 类型脚本公约
• 版本和更改

许可证

公务员制度委员会

组标签、标题大小和打印内容

这些选项是添加剂;现有默认情况保持不变.

import {
  CollapsibleHeadline,
  Headline,
  RadioButtonGroup,
} from '@dbcdk/react-components/client'

// The fieldset's legend stays above the controls. The existing div-based
// orientation/layout remains the default when `as` is omitted.
<RadioButtonGroup
  as="fieldset"
  label="Format"
  direction="row"
  options={[
    { label: 'PDF', value: 'pdf' },
    { label: 'Tekst', value: 'text' },
  ]}
  value={format}
  onChange={setFormat}
  helpText="Vælg ét format."
/>

// An h3 with the theme's 24px/xl type token, without changing heading semantics.
<Headline size={3} textSize="xl">Dokumentoplysninger</Headline>

// Closed on screen initially; includes its content when printing.
<CollapsibleHeadline header="Flere oplysninger" defaultExpanded={false} printExpanded>
  <p>Supplerende indhold.</p>
</CollapsibleHeadline>

Headline.textSize 接受 xs, (中文(简体) ), sm, (中文(简体) ), md, (中文(简体) ), lg, (中文(简体) ), xl,以及 2xl; 省略为 保留现有的响应标题表。 也致力于 CollapsibleHeadline。 。 。 .

printExpanded 将被倒闭的孩子挂在屏幕上 从键盘导航和无障碍树。 其状况和影响 保持活动。 违约仍未解除 儿童崩溃。 打印没有 改变扩张状态或其持续价值。 任何应用程序打印流程 必须仍然包括组件及其样式表.

RadioButtonGroup 将其标签、错误和帮助文本与组关联到 两种布局. InputContainer.labelId 也可用于自定义控制 需要引用其可见标签 aria-labelledby。 。 。 .

对于在窄屏幕上必须保持完全可读性的问题,请使用 <Accordion wrapHeaders items={items} mode="single" defaultOpenIndex={null} />。 。 。 . 页眉包是选入;现有的截取不变. 封闭的面板是 惰性并被隐藏在辅助技术中,包括打开后. 他们现有的动画和保留的儿童状态得以保存.

使用 Accordion variant="plain" 带有分隔符的轻量级问题列表 在行之间,不附加边框或背景. headerWeight 可选择 设置问题重 (400, 500, 600, 或 700); 现有的默认值为 400.

Accordion flushContent 从每个项目的内容中删除上下粘贴, 包括已填充的变体的开平面上间距. 水平内容编码 并保留每个大小和变体的页眉标记。 就像Tabs,这个 选项默认为 false,保持现有的间隔。 巢穴保留 他们自己的内容间隔, 即使在一个冲出Annion.

对于可重复使用的国家政策或持久性,导入 useAccordionState 从 客户端进入点 并让它拥有Annion的控制状态:

'use client'

import { Accordion, useAccordionState } from '@dbcdk/react-components/client'

const items = [
  { id: 'general', header: 'Generelt', children: <p>Generelle oplysninger</p> },
  { id: 'details', header: 'Detaljer', children: <p>Flere oplysninger</p> },
]

export function Details() {
  const { accordionProps, openAll, closeAll } = useAccordionState({
    itemIds: items.map(item => item.id),
    mode: 'multiple',
    initialOpen: 'all',
    storageKey: 'my-app-details', // Omit for in-memory state only.
  })

  return (
    <>
      <button onClick={openAll}>Åbn alle</button>
      <button onClick={closeAll}>Luk alle</button>
      <Accordion items={items} {...accordionProps} />
    </>
  )
}

itemIds 必须包含独特、非空、稳定的字符串,顺序与 items。钩子拒绝丢失或复制ID,而不是返回到 索引。 Annion本身仍然支持没有ID的项目.

initialOpen 是挂载时间默认值 : 'none' (默认), 'all',或数组 身份证 在单一模式下,只打开第一个有效的ID; 'all' 财务报告和审定财务报表 openAll() 打开第一个项目. closeAll() 崩溃一切。 结果也暴露了 openIds, (中文(简体) ), setOpenIds(ids),以及 hydrated。 。 。 .

与 storageKey,钩子使用库中本地Storage的持久性和 挂载后恢复。 服务器渲染和第一个客户端渲染相同 初始状态; hydrated 恢复完成时的信号。 已保存为空 数组故意会倒塌 数据畸形会回到默认值, 和无法使用的存储状态在内存中可用。 只保存了身份证,所以 重排会保持相同的部分打开;从列表中去掉的ID会被刷新. 对每个独立的手风琴都使用不同的钥匙. 在挂载钩子上切换密钥时, 新的密钥在写入前会恢复 或查取其保存的身份证.

打电话者可以提供 openIds 财务报告和审定财务报表 onOpenIdsChange 用于外部控制; 此选项将禁用所有存储读取和写入 。 坚持下去 让钩子自己来 状态和通过它 accordionProps {\fn黑体\fs22\bord1\shad0\3aHBE\4aH00\fscx67\fscy66\2cHFFFFFF\3cH808080}没有压倒他们 独立控制状态。 手风琴没有 storageKey 道具及其现有 控制/非控制道具和 defaultOpenIndexes="all" 保持不变.

单位 MarkdownEditor editOn="click",则 陆克 按钮旁边 伦克斯特 结束编辑, 保留当前值, 调用 onEditEnd,并恢复焦点 编辑按钮。 它的文本可以定制 labels.doneButton行动 也可以从预览和纯文本模式获得; 在文本区域保存中输入 它的正常新线行为。 在窄屏幕上,开关和按钮占用 他们自己的一行.