@weichenlin/swell-ui 0.1.0 → 0.3.0

package/README.md

@@ -2,7 +2,7 @@
 
 Hand-built React 19 components styled with Tailwind CSS v4: Badge, Button, Card, Checkbox,
 CheckboxGroup, Dialog, Drawer, Input (plus Search, Password and Copy), Meter, Select, Sidebar,
-Switch, Tabs, TabNav, ThemeSwitcher, Toast and Tooltip.
+Switch, Table, Tabs, TabNav, ThemeSwitcher, Toast and Tooltip.
 
 The package ships ESM, type declarations and two CSS files. Your app compiles the CSS with its own
 Tailwind v4, so the design tokens become your utilities too (`bg-primary`, `text-fg`, ...).
@@ -38,32 +38,180 @@ export function App() {
 }
 ```
 
-### Override tokens
+### Table
 
-Redefine any token after the import. Light values go in `@theme`; dark values in the same two dark
-blocks `theme.css` uses:
+Pass the current rows, column definitions, and a stable row ID. Add `search`, `sorting`, `pagination`,
+or `selection` to show controlled UI. The caller handles filtering, sorting, and fetching or slicing
+rows. The pagination `rowCount` is the total after filtering, before paging.
+
+```tsx
+import { Table } from '@weichenlin/swell-ui'
+
+;<Table
+  title="Deployments"
+  data={deployments}
+  getRowId={(row) => row.id}
+  columns={[
+    { id: 'service', header: 'Service', rowHeader: true, cell: (row) => row.service },
+    { id: 'duration', header: 'Duration', numeric: true, cell: (row) => row.duration },
+  ]}
+  emptyState="No deployments yet"
+  noResults="No matching deployments"
+/>
+```
+
+### Change the brand
+
+The default look is neutral gray with a near-black primary. A rebrand is two tokens, set once,
+after the import:
 
 ```css
 @import 'tailwindcss';
 @import '@weichenlin/swell-ui/styles.css';
 
 @theme {
-  --color-primary: #2563eb;
-  --radius-md: 6px;
+  --color-primary: #f7a501; /* buttons, input focus, checked switches and checkboxes, halos */
+  --color-primary-fg: #141413; /* text and marks drawn on the primary fill */
+}
+```
+
+That covers light, dark-from-the-system and `data-theme="dark"` alike. Input focus
+(`--color-input-focus`), checked controls (`--color-control-checked`, `-fg`) and the focus halo
+(`--color-input-halo`) are `var()` references to these two, resolved at runtime, so they follow.
+
+To use a different value per scheme, write both on one line with `light-dark()`:
+
+```css
+@theme {
+  --color-primary: light-dark(#2563eb, #60a5fa);
+  --color-primary-fg: light-dark(#ffffff, #0b1220);
+}
+```
+
+A light brand color (yellow, lime, cyan) can fall under 3:1 against the light page. The buttons
+stay readable through `--color-primary-fg`, but if the focus border or a checked box needs more
+contrast, override just that one:
+
+```css
+@theme {
+  --color-input-focus: light-dark(#b37700, #f7a501); /* darker amber on light only */
 }
+```
+
+Set tokens in `@theme` (or a plain `:root` rule) rather than on an inner element: the derived
+tokens are resolved on the root.
 
-:root[data-theme='dark'] {
-  --color-primary: #60a5fa;
+### Change the palette
+
+Colors come in two layers. A handful of **base colors** carry literal values; every other color
+token is computed from them at runtime (`var()` and `color-mix()`), so overriding a base color
+carries through to borders, muted text, fields, tints and so on:
+
+```css
+@theme {
+  --color-bg: light-dark(#f5f4ed, #141413);
+  --color-surface: light-dark(#faf9f5, #30302e);
+  --color-fg: light-dark(#141413, #faf9f5);
 }
-:root:not([data-theme='light']) {
-  @media (prefers-color-scheme: dark) {
-    --color-primary: #60a5fa;
-  }
+```
+
+The mix percentages are tuned so the default palette, and a warm one like the example above, pass WCAG contrast (text >=4.5:1,
+field borders >=3:1). A palette far from these (a mid-tone page, low-contrast text) can fall
+short, so check contrast after changing `bg`, `surface` or `fg`. Any computed token can still be
+overridden on its own.
+
+Override at the root (`@theme` or `:root`): computed tokens are resolved there, so a base color
+set on an inner element does not reach them.
+
+### Tokens
+
+Every pair is written `light-dark(<light>, <dark>)`; override it the same way, once. All color
+tokens are also Tailwind utilities (`bg-surface`, `text-fg-muted`, `border-input-border`, ...).
+
+**Base colors**
+
+| Token                                   | Used for                                               |
+| --------------------------------------- | ------------------------------------------------------ |
+| `--color-bg`                            | Page background                                        |
+| `--color-surface`                       | Cards, panels and text fields                          |
+| `--color-surface-raised`                | Popovers and dialogs                                   |
+| `--color-fg`                            | Text                                                   |
+| `--color-primary`, `--color-primary-fg` | Brand fill and the text on it. Default: `fg` (neutral) |
+| `--color-focus`                         | Keyboard focus outline (blue)                          |
+| `--color-{danger,success,warning,info}` | Status tones: solid fill, icon, and danger text        |
+
+**Computed** (from the base colors; override only to fine-tune)
+
+| Token                                                         | Used for                                                         | Computed from                                                            |
+| ------------------------------------------------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------ |
+| `--color-accent`                                              | Secondary brand color; unused by components                      | `primary`                                                                |
+| `--color-surface-muted`                                       | Hover fills, secondary button                                    | fg into bg                                                               |
+| `--color-fg-strong`, `-fg-muted`, `-fg-subtle`                | Text from strong to quiet (`fg-subtle` >=4.5:1 on every surface) | fg into bg                                                               |
+| `--color-border`, `-border-strong`, `-ring`, `-ring-deep`     | Dividers, hairlines, 1px button and tab-list rings               | fg into bg                                                               |
+| `--color-inverse`, `-inverse-fg`                              | `dark` button, tooltips                                          | fg into bg; the page on dark                                             |
+| `--color-input-bg`, `-input-bg-hover`                         | Text field fill (read-only fields use `bg`)                      | `surface`                                                                |
+| `--color-input-border`, `-input-border-hover`                 | Field border; also the off track of Switch and box of Checkbox   | fg into bg; `fg-strong`                                                  |
+| `--color-input-placeholder`                                   | Placeholder text                                                 | fg into bg                                                               |
+| `--color-input-focus`, `-input-halo`                          | Focused field border and its 3px ring                            | `primary`; input-focus at 14%                                            |
+| `--color-input-halo-invalid`, `-invalid-focus`                | Same ring for invalid fields                                     | danger at 12% / 22%                                                      |
+| `--color-control-checked`, `-control-checked-fg`              | Checked Switch/Checkbox fill and the check on it                 | `primary` / `primary-fg`                                                 |
+| `--color-switch-handle`, `-switch-handle-checked`             | Switch thumb, off / on                                           | off: `surface-raised` / dark `fg`; on: white or black by track lightness |
+| `--color-popover-bg`, `-popover-border`, `-popover-highlight` | Select picker and dialogs; highlight is the active row           | `surface-raised`, fg into it                                             |
+| `--color-dialog-backdrop`                                     | Dimmed page behind Dialog and Drawer                             | fg at 40%; black at 60% on dark                                          |
+| `--color-neutral`                                             | Neutral status tone                                              | fg into bg                                                               |
+| `--color-{tone}-fg`                                           | Text on a solid status fill                                      | `surface` / `bg`                                                         |
+| `--color-{tone}-subtle-bg`, `-border`                         | Tinted badge and its hairline                                    | tone into bg                                                             |
+| `--color-{tone}-subtle-fg`                                    | Text on the tinted badge (>=5:1)                                 | tone pushed toward fg                                                    |
+
+Shadows (`--shadow-input`, `-input-lift`, `-switch-thumb`, `-popover`, `-dialog`, `-whisper`) and
+the input highlight are black or white at low opacity: they shade, so they have no palette color.
+`--container-page` is `max-w-page` (1200px).
+
+### Serif headings
+
+```css
+@import 'tailwindcss';
+@import '@weichenlin/swell-ui/styles.css';
+@import '@weichenlin/swell-ui/typography.css'; /* h1-h3 in the serif stack, weight 500 */
+```
+
+### Fonts
+
+swell-ui sets no font names: text uses Tailwind's `--font-sans` (the system UI stack), and
+`font-serif` / `font-mono` are Tailwind's defaults too. To use a web font, ship its files with
+your app, for example with [Fontsource](https://fontsource.org):
+
+```sh
+pnpm add @fontsource-variable/inter
+```
+
+```css
+@import 'tailwindcss';
+@import '@fontsource-variable/inter';
+@import '@weichenlin/swell-ui/styles.css';
+
+@theme {
+  --font-sans: 'Inter Variable', ui-sans-serif, system-ui, sans-serif;
 }
 ```
 
-Note that the theme replaces Tailwind's `rounded-sm/md/lg` values (6, 8 and 12px) and adds
-`rounded-sharp` (4px), shadows (`shadow-popover`, `shadow-dialog`, ...) and `max-w-page`.
+### Radius
+
+swell-ui does not touch Tailwind's radius scale; components use the stock `rounded-*` classes, so
+`rounded-md` is still 6px in your app. Changing `--radius-*` in your `@theme` changes the
+components too.
+
+Coming from 0.1, which replaced the scale: shift each class one step up to keep the old size.
+
+| 0.1 class       | px  | Now           |
+| --------------- | --- | ------------- |
+| `rounded-sharp` | 4   | `rounded-sm`  |
+| `rounded-sm`    | 6   | `rounded-md`  |
+| `rounded-md`    | 8   | `rounded-lg`  |
+| `rounded-lg`    | 12  | `rounded-xl`  |
+| `rounded-xl`    | 16  | `rounded-2xl` |
+| `rounded-2xl`   | 24  | `rounded-3xl` |
+| `rounded-3xl`   | 32  | `rounded-4xl` |
 
 ### Tokens only
 
@@ -78,7 +226,8 @@ instead:
 ### `cn`
 
 `cn` (clsx + tailwind-merge) is exported and knows the custom tokens, so
-`cn('rounded-sharp', 'rounded-md')` gives `rounded-md`.
+`cn('text-fg-muted', 'text-danger')` gives `text-danger` and `cn('shadow-popover', 'shadow-none')`
+gives `shadow-none`.
 
 ## Dark mode
 
@@ -86,6 +235,10 @@ Without a `data-theme` attribute the theme follows the system (`prefers-color-sc
 `data-theme="light"` or `data-theme="dark"` on `<html>` forces one. The `dark:` variant follows the
 same rule.
 
+Under the hood the root's `color-scheme` is `light dark`, `light` or `dark` accordingly, and every
+color token picks its side with `light-dark()`. Browsers support it natively from Chrome 123,
+Safari 17.5 and Firefox 120; Tailwind's production build rewrites it for older targets.
+
 `useTheme` persists the choice and sets the attribute; `ThemeSwitcher` is the toggle button:
 
 ```tsx
@@ -166,6 +319,23 @@ links do) closes it.
 </TabNav>
 ```
 
+`Button` takes `asChild` too, for a navigation that should look like a button. It keeps the
+button's look, icons and ripple, and stays a real link (open in a new tab, copy the URL):
+
+```tsx
+<Button asChild intent="secondary" iconLeft={<Plus />}>
+  <Link to="/apps/new">New app</Link>
+</Button>
+
+<Button asChild icon={<Settings />} aria-label="Settings">
+  <Link to="/settings" />
+</Button>
+```
+
+`disabled` (with or without `disabledReason`) works as on the button: the link stays focusable with
+`aria-disabled`, and clicks are stopped before your Link sees them, so it never navigates. `loading`
+and `type` are button-only.
+
 ## Develop
 
 Node 26.11.1 (`.node-version`, via fnm) and pnpm 12.
@@ -177,11 +347,11 @@ pnpm test             # vitest (jsdom)
 pnpm typecheck        # tsc -b
 pnpm lint             # vp check: format, lint, type-aware lint
 pnpm knip             # unused files, exports and dependencies
-pnpm build            # vp pack -> dist/index.js, index.d.ts, theme.css, styles.css
+pnpm build            # vp pack -> dist/index.js, index.d.ts and the CSS files
 pnpm build-storybook
 ```
 
-`src/styles/theme.css` and `src/styles/styles.css` are copied into `dist/` as they are, so the
+The CSS files under `src/styles/` are copied into `dist/` as they are, so the
 `@source "./*.js"` in `styles.css` is relative to `dist/`. Storybook and the lint use
 `src/styles/dev.css`, which adds Tailwind and scans `src/` and `stories/`.
 

package/dist/index.d.ts

@@ -1,6 +1,21 @@
 import { ClassValue } from "clsx";
 import { VariantProps } from "class-variance-authority";
-import { ComponentProps, MouseEvent, ReactElement, ReactNode } from "react";
+import { ComponentProps, MouseEvent, MouseEventHandler, ReactElement, ReactNode } from "react";
+//#region src/components/alert/alert.d.ts
+type AlertTone = 'neutral' | 'info' | 'success' | 'warning' | 'danger';
+type AlertProps = Omit<ComponentProps<'div'>, 'title'> & {
+  tone?: AlertTone;
+  title?: ReactNode;
+  /** An action such as a retry button or a link to settings. */
+  action?: ReactNode;
+  /** Shows the dismiss button. The caller controls whether the Alert stays mounted. */
+  onDismiss?: MouseEventHandler<HTMLButtonElement>;
+  /** Accessible name of the dismiss button. */
+  dismissLabel?: string;
+};
+/** A persistent message shown next to the content it describes. Use a live region for updates that need announcing. */
+export declare function Alert({ tone, title, action, onDismiss, dismissLabel, className, children, ...props }: AlertProps): import("react").JSX.Element;
+//#endregion
 //#region src/components/badge/badge.d.ts
 type BadgeTone = 'neutral' | 'info' | 'success' | 'warning' | 'danger';
 type BadgeVariant = 'subtle' | 'outline' | 'solid';
@@ -63,14 +78,28 @@ type BaseProps = Omit<ComponentProps<'button'>, 'children'> & Omit<VariantProps<
   /** Material-style press ripple; on by default. */
   ripple?: boolean;
 };
+/** With `asChild` the host is your element (a router Link): loading and `type` are button-only. */
+type AsChildProps = {
+  /**
+   * Render the only child (e.g. a router Link) instead of a `<button>`, with the button's props,
+   * classes, ref and content merged into it.
+   */
+  asChild: true;
+  children: ReactElement;
+  loading?: never;
+  loadingText?: never;
+  type?: never;
+};
 type TextButtonProps = BaseProps & {
   icon?: never;
   iconLeft?: ReactNode;
   iconRight?: ReactNode;
-  children?: ReactNode;
   tooltip?: never;
   tooltipSide?: never;
-};
+} & ({
+  asChild?: false;
+  children?: ReactNode;
+} | AsChildProps);
 type IconOnlyButtonProps = Omit<BaseProps, 'aria-label' | 'fullWidth'> & {
   /** Renders a square icon-only button. */
   icon: NonNullable<ReactNode>;
@@ -80,10 +109,12 @@ type IconOnlyButtonProps = Omit<BaseProps, 'aria-label' | 'fullWidth'> & {
   tooltip?: boolean;
   tooltipSide?: TooltipProps['side'];
   fullWidth?: never;
-  children?: never;
   iconLeft?: never;
   iconRight?: never;
-};
+} & ({
+  asChild?: false;
+  children?: never;
+} | AsChildProps);
 type ButtonProps = TextButtonProps | IconOnlyButtonProps;
 export declare function Button(props: ButtonProps): import("react").JSX.Element;
 //#endregion
@@ -460,6 +491,75 @@ type SwitchProps = NativeSwitchProps & ChoiceLabelProps & {
 };
 export declare function Switch({ label, description, error, size, loading, labelPosition, className, inputClassName, disabled, onChange, 'aria-describedby': describedBy, 'aria-invalid': ariaInvalid, ...props }: SwitchProps): import("react").JSX.Element;
 //#endregion
+//#region src/components/table/table.d.ts
+type TableColumn<T> = {
+  id: string;
+  header: ReactNode;
+  cell: (row: T) => ReactNode;
+  sortable?: boolean;
+  align?: 'start' | 'center' | 'end';
+  numeric?: boolean;
+  rowHeader?: boolean;
+  className?: string;
+  headerClassName?: string;
+};
+type TableSort = {
+  id: string;
+  direction: 'asc' | 'desc';
+};
+declare const labels: {
+  search: string;
+  clearSelection: string;
+  selectPage: string;
+  selectRow: (id: string) => string;
+  selectionCount: (count: number) => string;
+  scrollRegion: string;
+  pagination: string;
+  previousPage: string;
+  nextPage: string;
+  page: (page: number, count: number) => string;
+  range: (first: number, last: number, total: number) => string;
+  emptyState: string;
+  noResults: string;
+};
+type TableProps<T> = Omit<ComponentProps<'table'>, 'title' | 'children' | 'className'> & {
+  /** Rows to render on the current page, in display order. */
+  data: readonly T[];
+  columns: readonly TableColumn<T>[];
+  getRowId: (row: T) => string;
+  title?: ReactNode;
+  emptyState?: ReactNode;
+  noResults?: ReactNode;
+  /** Indicates filtering when the caller applies filters outside the search field. */
+  filtered?: boolean;
+  /** Controlled UI. The caller supplies the resulting data. */
+  search?: {
+    value: string;
+    onChange: (value: string) => void;
+  };
+  sorting?: {
+    value: TableSort | null;
+    onChange: (value: TableSort | null) => void;
+  };
+  pagination?: {
+    /** Zero-based page index. */
+    pageIndex: number;
+    pageSize: number;
+    rowCount: number;
+    onPageChange: (pageIndex: number) => void;
+  };
+  selection?: {
+    ids: ReadonlySet<string>;
+    onChange: (ids: Set<string>) => void;
+    canSelectRow?: (row: T) => boolean;
+  };
+  /** Root element classes. Use `tableClassName` for column layout or minimum width. */
+  className?: string;
+  tableClassName?: string;
+  labels?: Partial<typeof labels>;
+};
+export declare function Table<T>({ data, columns, getRowId, title, emptyState, noResults, filtered, search, sorting, pagination, selection, className, tableClassName, labels: labelOverrides, ...props }: TableProps<T>): import("react").JSX.Element;
+//#endregion
 //#region src/components/tabs/shared.d.ts
 type TabsVariant = 'line' | 'segmented';
 type TabsSize = 'sm' | 'md';
@@ -656,4 +756,4 @@ export declare function Toaster(props: ToasterProps): import("react").ReactPorta
 //#region src/lib/cn.d.ts
 export declare function cn(...inputs: ClassValue[]): string;
 //#endregion
-export type { BadgeProps, BadgeTone, ButtonProps, CardHeaderProps, CardProps, CheckboxGroupProps, CheckboxProps, CopyInputProps, DialogCloseReason, DialogHeaderProps, DialogProps, DialogSize, DrawerCloseProps, DrawerCloseReason, DrawerHeaderProps, DrawerProps, DrawerSide, DrawerSize, InputProps, MeterProps, MeterSegment, MeterTone, PasswordInputProps, SearchInputProps, SelectGroup, SelectOption, SelectProps, SidebarGroupProps, SidebarItemProps, SidebarProps, SidebarTriggerProps, SwitchProps, SwitchSize, TabListProps, TabNavLinkProps, TabNavProps, TabPanelProps, TabProps, TabsActivationMode, TabsProps, TabsSize, TabsVariant, Theme, ThemeSwitcherProps, ToastActionButton, ToastOptions, ToastPatch, ToastPosition, ToastPromiseOptions, ToastType, ToasterProps, TooltipProps, UseThemeOptions };
+export type { AlertProps, AlertTone, BadgeProps, BadgeTone, ButtonProps, CardHeaderProps, CardProps, CheckboxGroupProps, CheckboxProps, CopyInputProps, DialogCloseReason, DialogHeaderProps, DialogProps, DialogSize, DrawerCloseProps, DrawerCloseReason, DrawerHeaderProps, DrawerProps, DrawerSide, DrawerSize, InputProps, MeterProps, MeterSegment, MeterTone, PasswordInputProps, SearchInputProps, SelectGroup, SelectOption, SelectProps, SidebarGroupProps, SidebarItemProps, SidebarProps, SidebarTriggerProps, SwitchProps, SwitchSize, TabListProps, TabNavLinkProps, TabNavProps, TabPanelProps, TabProps, TableColumn, TableProps, TableSort, TabsActivationMode, TabsProps, TabsSize, TabsVariant, Theme, ThemeSwitcherProps, ToastActionButton, ToastOptions, ToastPatch, ToastPosition, ToastPromiseOptions, ToastType, ToasterProps, TooltipProps, UseThemeOptions };