@weichenlin/swell-ui 0.2.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,6 +38,28 @@ export function App() {
 }
 ```
 
+### Table
+
+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,
@@ -79,49 +101,80 @@ contrast, override just that one:
 Set tokens in `@theme` (or a plain `:root` rule) rather than on an inner element: the derived
 tokens are resolved on the root.
 
+### 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);
+}
+```
+
+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 color token is a `light-dark(<light>, <dark>)` pair; override it the same way, once. All of
-them are also Tailwind utilities (`bg-surface`, `text-fg-muted`, `border-input-border`, ...).
-
-| Token                                                                               | Used for                                                                           |
-| ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
-| `--color-primary`, `--color-primary-fg`                                             | Brand fill and the text on it                                                      |
-| `--color-accent`                                                                    | Secondary brand color; unused by components, defaults to primary                   |
-| `--color-bg`                                                                        | Page background                                                                    |
-| `--color-surface`, `-surface-raised`, `-surface-muted`                              | Cards and panels; raised (tooltips, sheets); muted (hover fills, secondary button) |
-| `--color-fg`, `-fg-strong`, `-fg-muted`, `-fg-subtle`                               | Text, from strongest to quietest (`fg-subtle` stays >=4.5:1)                       |
-| `--color-border`, `-border-strong`                                                  | Dividers and hairlines                                                             |
-| `--color-ring`, `-ring-deep`                                                        | 1px button and tab-list rings                                                      |
-| `--color-inverse`, `-inverse-fg`                                                    | `dark` button, tooltips                                                            |
-| `--color-focus`                                                                     | Keyboard focus outline (blue)                                                      |
-| `--color-input-bg`, `-input-bg-hover`                                               | Text field fill                                                                    |
-| `--color-input-border`, `-input-border-hover`                                       | Text field border; also the off track of Switch and box of Checkbox                |
-| `--color-input-placeholder`                                                         | Placeholder text                                                                   |
-| `--color-input-focus`                                                               | Focused field border. Default: `var(--color-primary)`                              |
-| `--color-input-halo`                                                                | 3px ring around a focused field. Default: input-focus at 14%                       |
-| `--color-input-halo-invalid`, `-invalid-focus`                                      | Same ring for invalid fields (danger at 12% / 22%)                                 |
-| `--color-input-highlight`                                                           | Inset top highlight on fields                                                      |
-| `--color-control-checked`, `-control-checked-fg`                                    | Checked Switch/Checkbox fill and its mark. Default: primary / primary-fg           |
-| `--color-popover-bg`, `-popover-border`, `-popover-highlight`                       | Select picker, dialogs; highlight is the active row                                |
-| `--color-dialog-backdrop`                                                           | Dimmed page behind Dialog and Drawer                                               |
-| `--color-{success,warning,danger,info,neutral}`                                     | Status tone: solid fill / icon                                                     |
-| `--color-{tone}-fg`                                                                 | Text on the solid fill                                                             |
-| `--color-{tone}-subtle-bg`, `-subtle-fg`, `-border`                                 | Tinted badge, its text and hairline                                                |
-| `--shadow-input`, `-input-lift`, `-switch-thumb`, `-popover`, `-dialog`, `-whisper` | Elevation (`shadow-*` utilities)                                                   |
-| `--container-page`                                                                  | `max-w-page` (1200px)                                                              |
-
-### Optional looks
+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/themes/warm.css'; /* parchment surfaces, brown primary */
 @import '@weichenlin/swell-ui/typography.css'; /* h1-h3 in the serif stack, weight 500 */
 ```
 
-Both are independent; your own `@theme` overrides go after them.
-
 ### Fonts
 
 swell-ui sets no font names: text uses Tailwind's `--font-sans` (the system UI stack), and
@@ -266,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.

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 };