@grampro/kit 0.0.0-stage → 2.4.0

package/source/components/checkbox/react/CheckboxGroup.tsx

@@ -0,0 +1,149 @@
+"use client";
+
+import { useId, useMemo, type CSSProperties, type ReactNode } from "react";
+import { useControllableState } from "../../shared/react/useControllableState";
+import { describeField } from "../../shared/core/field";
+import { groupState, toggleAll, toggleValue } from "../core/group";
+import type { CheckboxLocaleText, CheckboxOption, CheckboxSize } from "../core/types";
+import { Checkbox } from "./Checkbox";
+import { CheckboxGroupContext, type CheckboxGroupContextValue } from "./context";
+import { defaultCheckboxText } from "./locale";
+import { cx, type CheckboxGroupSlot } from "./props";
+
+export interface CheckboxGroupProps {
+  /** Checked values (controlled). */
+  value?: string[];
+  defaultValue?: string[];
+  onValueChange?(values: string[]): void;
+  /** Render these options, or pass `<Checkbox value="…">` children. */
+  options?: readonly CheckboxOption[];
+  children?: ReactNode;
+  /** The group's name, shown as its legend. */
+  label?: ReactNode;
+  description?: ReactNode;
+  error?: ReactNode;
+  required?: boolean;
+  disabled?: boolean;
+  /** Form field name for every checkbox in the group. */
+  name?: string;
+  size?: CheckboxSize;
+  /** Default `vertical`. */
+  orientation?: "vertical" | "horizontal";
+  /** With `options`, a parent box that checks or clears them all. `true` uses the default label. */
+  selectAll?: boolean | ReactNode;
+  id?: string;
+  className?: string;
+  classNames?: Partial<Record<CheckboxGroupSlot, string>>;
+  style?: CSSProperties;
+  localeText?: Partial<CheckboxLocaleText>;
+}
+
+/** A labelled set of checkboxes sharing one array of values. */
+export function CheckboxGroup(props: CheckboxGroupProps) {
+  const {
+    value,
+    defaultValue,
+    onValueChange,
+    options,
+    children,
+    label,
+    description,
+    error,
+    required = false,
+    disabled = false,
+    name,
+    size,
+    orientation = "vertical",
+    selectAll,
+    id: idProp,
+    className,
+    classNames,
+    style,
+    localeText,
+  } = props;
+
+  const reactId = useId();
+  const id = idProp ?? reactId;
+  const text = useMemo(() => ({ ...defaultCheckboxText, ...localeText }), [localeText]);
+  const [values, setValues] = useControllableState<string[]>(value, defaultValue ?? []);
+
+  const context = useMemo<CheckboxGroupContextValue>(() => {
+    const commit = (next: string[]) => {
+      setValues(next);
+      onValueChange?.(next);
+    };
+    return {
+      values,
+      toggle: (item, checked) => commit(toggleValue(values, item, checked)),
+      name,
+      disabled,
+      invalid: Boolean(error),
+      size,
+    };
+  }, [values, setValues, onValueChange, name, disabled, error, size]);
+
+  const showSelectAll = Boolean(selectAll) && options !== undefined && options.length > 0;
+  const describedBy = describeField(id, { description, error });
+
+  return (
+    <fieldset
+      id={id}
+      className={cx("ck-group", classNames?.root, className)}
+      style={style}
+      // A disabled fieldset disables every control inside it natively.
+      disabled={disabled}
+      aria-describedby={describedBy}
+      data-orientation={orientation}
+      data-select-all={showSelectAll || undefined}
+      data-invalid={error ? "" : undefined}
+    >
+      {label && (
+        <legend className={cx("ck-legend", classNames?.legend)} data-required={required || undefined}>
+          {label}
+        </legend>
+      )}
+      {description && (
+        <span id={`${id}-description`} className={cx("ck-description", classNames?.description)}>
+          {description}
+        </span>
+      )}
+
+      {showSelectAll && (
+        <Checkbox
+          className="ck-select-all"
+          label={selectAll === true ? text.selectAll : selectAll}
+          size={size}
+          disabled={disabled}
+          checked={groupState(values, options)}
+          onCheckedChange={() => {
+            const next = toggleAll(values, options);
+            setValues(next);
+            onValueChange?.(next);
+          }}
+        />
+      )}
+
+      <CheckboxGroupContext value={context}>
+        <div className={cx("ck-items", classNames?.items)}>
+          {options
+            ? options.map((option) => (
+                <Checkbox
+                  key={option.value}
+                  value={option.value}
+                  label={option.label}
+                  description={option.description}
+                  disabled={option.disabled}
+                />
+              ))
+            : children}
+        </div>
+      </CheckboxGroupContext>
+
+      {error && (
+        <span id={`${id}-error`} className={cx("ck-error", classNames?.error)} role="alert">
+          {error}
+        </span>
+      )}
+    </fieldset>
+  );
+}

package/source/components/checkbox/react/context.ts

@@ -0,0 +1,16 @@
+"use client";
+
+import { createContext } from "react";
+import type { CheckboxSize } from "../core/types";
+
+export interface CheckboxGroupContextValue {
+  values: readonly string[];
+  toggle(value: string, checked: boolean): void;
+  name?: string;
+  disabled: boolean;
+  invalid: boolean;
+  size?: CheckboxSize;
+}
+
+/** Lets each Checkbox inside a CheckboxGroup read and change the group's values. */
+export const CheckboxGroupContext = createContext<CheckboxGroupContextValue | null>(null);

package/source/components/checkbox/react/locale.ts

@@ -0,0 +1,5 @@
+import type { CheckboxLocaleText } from "../core/types";
+
+export const defaultCheckboxText: CheckboxLocaleText = {
+  selectAll: "Select all",
+};

package/source/components/checkbox/react/props.ts

@@ -0,0 +1,6 @@
+export type CheckboxSlot = "root" | "control" | "input" | "label" | "description" | "error";
+
+export type CheckboxGroupSlot = "root" | "legend" | "description" | "items" | "error";
+
+// Shared with every other component, so class handling cannot drift.
+export { cx } from "../../shared/core/cx";

package/source/components/checkbox/styles.css

@@ -0,0 +1,211 @@
+/*
+ * Checkbox and CheckboxGroup styles.
+ *
+ * The box is the native <input> with `appearance: none`, so it keeps native
+ * behavior. Tokens read the shared --gbs-* variables when they are set on an
+ * ancestor (set them on :root to theme every component at once). Rules are
+ * unlayered: they beat a framework reset on specificity, and lose to anything
+ * you pass through `className`. With Tailwind v4, import this file after the
+ * framework and inside its components layer - see the README.
+ */
+
+.ck-root,
+.ck-group {
+  --ck-fg: var(--gbs-fg, var(--dg-fg, light-dark(#18181b, #f4f4f5)));
+  --ck-muted: var(--gbs-muted, var(--dg-muted, light-dark(#71717a, #a1a1aa)));
+  --ck-border: var(--gbs-border-control, light-dark(#a1a1aa, #52525b));
+  --ck-input-bg: var(--gbs-input-bg, var(--dg-input-bg, light-dark(#ffffff, #121216)));
+  --ck-accent: var(--gbs-accent, var(--dg-accent, light-dark(#2563eb, #60a5fa)));
+  --ck-accent-fg: var(--gbs-accent-fg, var(--dg-accent-fg, light-dark(#ffffff, #0b1220)));
+  --ck-focus: var(--gbs-focus, var(--dg-focus, light-dark(#2563eb, #60a5fa)));
+  --ck-danger: var(--gbs-danger, var(--dg-danger, light-dark(#dc2626, #f87171)));
+  --ck-font-size: var(--gbs-font-size, var(--dg-font-size, 13px));
+  --ck-size: 16px;
+  --ck-radius: 4px;
+
+  color-scheme: inherit;
+  font-size: var(--ck-font-size);
+  line-height: 1.4;
+  color: var(--ck-fg);
+}
+
+:where(.dark, [data-theme="dark"]) :is(.ck-root, .ck-group) {
+  color-scheme: dark;
+}
+:where(.light, [data-theme="light"]) :is(.ck-root, .ck-group) {
+  color-scheme: light;
+}
+
+:where(.ck-root, .ck-group) *,
+:where(.ck-root, .ck-group) *::before,
+:where(.ck-root, .ck-group) *::after {
+  box-sizing: border-box;
+}
+
+.ck-root {
+  display: flex;
+  align-items: flex-start;
+  gap: 8px;
+  min-width: 0;
+}
+.ck-root[data-size="sm"] {
+  --ck-size: 14px;
+  --ck-font-size: 12px;
+}
+.ck-root[data-size="lg"] {
+  --ck-size: 20px;
+  --ck-font-size: 14px;
+  --ck-radius: 5px;
+}
+
+/* ---------------------------------------------------------------- box */
+
+.ck-control {
+  position: relative;
+  display: grid;
+  flex: none;
+  width: var(--ck-size);
+  height: var(--ck-size);
+  /* Center the box on the first line of the label. */
+  margin-top: calc((1.4em - var(--ck-size)) / 2);
+}
+
+.ck-input {
+  grid-area: 1 / 1;
+  width: 100%;
+  height: 100%;
+  margin: 0;
+  appearance: none;
+  border: 1.5px solid var(--ck-border);
+  border-radius: var(--ck-radius);
+  background: var(--ck-input-bg);
+  cursor: pointer;
+  transition:
+    background-color 120ms ease,
+    border-color 120ms ease;
+}
+.ck-input:hover:not(:disabled) {
+  border-color: color-mix(in oklab, var(--ck-border), var(--ck-fg) 35%);
+}
+.ck-input:focus-visible {
+  outline: 2px solid var(--ck-focus);
+  outline-offset: 2px;
+}
+.ck-input:is(:checked, :indeterminate) {
+  border-color: var(--ck-accent);
+  background: var(--ck-accent);
+}
+.ck-root[data-invalid] .ck-input:not(:checked, :indeterminate) {
+  border-color: var(--ck-danger);
+}
+.ck-input:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+.ck-icon {
+  grid-area: 1 / 1;
+  width: 100%;
+  height: 100%;
+  fill: none;
+  stroke: var(--ck-accent-fg);
+  stroke-width: 2;
+  stroke-linecap: round;
+  stroke-linejoin: round;
+  pointer-events: none;
+}
+.ck-check {
+  stroke-dasharray: 1;
+  stroke-dashoffset: 1;
+  transition: stroke-dashoffset 160ms ease;
+}
+.ck-dash {
+  opacity: 0;
+}
+.ck-input:checked:not(:indeterminate) + .ck-icon .ck-check {
+  stroke-dashoffset: 0;
+}
+.ck-input:indeterminate + .ck-icon .ck-dash {
+  opacity: 1;
+}
+
+/* --------------------------------------------------------------- text */
+
+.ck-text {
+  display: flex;
+  flex-direction: column;
+  gap: 1px;
+  min-width: 0;
+}
+.ck-label {
+  cursor: pointer;
+}
+.ck-root[data-disabled] .ck-label {
+  color: var(--ck-muted);
+  cursor: not-allowed;
+}
+.ck-label[data-required]::after,
+.ck-legend[data-required]::after {
+  content: " *";
+  color: var(--ck-danger);
+}
+.ck-description {
+  color: var(--ck-muted);
+  font-size: 0.92em;
+}
+.ck-error {
+  color: var(--ck-danger);
+  font-size: 0.92em;
+}
+
+/* -------------------------------------------------------------- group */
+
+.ck-group {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  min-width: 0;
+  margin: 0;
+  padding: 0;
+  border: 0;
+}
+.ck-legend {
+  /* A floated legend joins the flex gap like any other child. */
+  float: left;
+  width: 100%;
+  margin-bottom: 2px;
+  padding: 0;
+  font-weight: 500;
+}
+.ck-legend + * {
+  clear: both;
+}
+.ck-items {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+.ck-group[data-orientation="horizontal"] .ck-items {
+  flex-flow: row wrap;
+  gap: 8px 20px;
+}
+.ck-group[data-select-all] .ck-items {
+  padding-inline-start: calc(var(--ck-size) + 8px);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .ck-input,
+  .ck-check {
+    transition: none;
+  }
+}
+
+@media (forced-colors: active) {
+  .ck-input:is(:checked, :indeterminate) {
+    background: Highlight;
+    border-color: Highlight;
+  }
+  .ck-icon {
+    stroke: HighlightText;
+  }
+}

package/source/components/combobox/README.md

@@ -0,0 +1,170 @@
+# Combobox: Select and MultiSelect
+
+Two value pickers with option search, built on one engine and styled to match
+the DataGrid. No runtime dependencies besides React 19.
+
+- **`<Select>`** — one value.
+- **`<MultiSelect>`** — many values, shown as tags.
+
+Both support client or server options, grouping, descriptions, disabled
+options, virtualization for long lists, creating new options, forms, full
+keyboard control, dark mode and right-to-left layouts.
+
+## Setup
+
+```ts
+import { MultiSelect, Select } from "@/components/combobox";
+import "@/components/combobox/styles.css";
+```
+
+The stylesheet reads the shared `--gbs-*` variables when you set them on
+`:root`, so every component in the library shares one theme, and falls back to
+the same default palette otherwise.
+
+## Basic usage
+
+```tsx
+const countries = [
+  { value: "in", label: "India", group: "Asia" },
+  { value: "de", label: "Germany", group: "Europe", description: "Berlin" },
+  { value: "mx", label: "Mexico", group: "Americas", disabled: true },
+];
+
+const [country, setCountry] = useState<string | null>(null);
+
+<Select label="Country" options={countries} value={country} onChange={setCountry} />;
+
+const [tags, setTags] = useState<string[]>([]);
+<MultiSelect label="Tags" options={tagOptions} value={tags} onChange={setTags} max={5} />;
+```
+
+Both are controlled with `value` + `onChange`, or uncontrolled with
+`defaultValue`. `onChange` also receives the full option objects:
+`onChange={(value, option) => …}` (single) and `(values, options) => …` (multi).
+
+## Options
+
+```ts
+interface ComboboxOption<V = string> {
+  value: V;              // string or number
+  label: string;
+  description?: string;  // second line
+  group?: string;        // heading; groups appear in first-seen order
+  disabled?: boolean;
+  icon?: ReactNode;
+  keywords?: string[];   // extra search terms
+}
+```
+
+Search matches the label (and highlights it), the description and keywords.
+
+## Props
+
+Shared by both components:
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `options` | `ComboboxOption<V>[]` | required | Options to show. |
+| `mode` | `"client"` \| `"server"` | `"client"` | `server` skips local filtering; `options` are the current results. |
+| `loading` | `boolean` | `false` | Shows a spinner; keeps current options visible. |
+| `onSearchChange` | `(search: string) => void` | — | Search text; debounced in server mode, and fired on open. |
+| `searchDebounce` | `number` | `250` | Debounce in milliseconds (server mode). |
+| `searchable` | `boolean` | `true` | Show the search box. When `false`, typing jumps to a matching option. |
+| `hasMore` / `onLoadMore` | `boolean` / `() => void` | — | Paging: called when the list nears its end, plus a "Load more" button. |
+| `filterFn` | `(option, search) => boolean` | — | Replaces the built-in matching (client mode). |
+| `renderOption` | `(option, { selected, active }) => ReactNode` | — | Custom option content. |
+| `allowCreate` / `onCreate` | `boolean` / `(label: string) => void` | — | Offers "Create …" when nothing matches. |
+| `label`, `description`, `error` | `ReactNode` | — | Field label, hint and error message. `error` also marks the control invalid. |
+| `placeholder` | `string` | `"Select…"` | Shown when nothing is selected. |
+| `required`, `disabled` | `boolean` | `false` | Field states. |
+| `clearable` | `boolean` | `true` | Show the clear button. |
+| `size` | `"sm"` \| `"md"` \| `"lg"` | `"md"` | Control height and font size. |
+| `name` | `string` | — | Posts hidden inputs for forms (one per value). |
+| `maxHeight` | `number` | `280` | Max height of the list. |
+| `virtualize` | `boolean` \| `number` | `true` | Virtualizes above 80 options; pass a number to change the threshold. |
+| `emptyMessage` | `ReactNode` | "No options found" | Shown when nothing matches. |
+| `className`, `classNames`, `style` | — | — | Styling hooks. Slots: `root`, `label`, `control`, `value`, `tag`, `popover`, `search`, `list`, `option`, `footer`. |
+| `localeText` | `Partial<ComboboxLocaleText>` | English | Overrides UI text. |
+| `onOpenChange` | `(open: boolean) => void` | — | Fires when the list opens or closes. |
+| `ref` | `Ref<ComboboxHandle<V>>` | — | `open()`, `close()`, `toggle()`, `focus()`, `clear()`, `getValue()`, `getSelectedOptions()`. |
+
+`Select` adds `value` / `defaultValue` (`V | null`) and `closeOnSelect`
+(default `true`). `MultiSelect` adds `value` / `defaultValue` (`V[]`), `max`,
+`maxVisibleTags` (default 3), `showSelectAll` (default `true`) and
+`closeOnSelect` (default `false`).
+
+## Server options
+
+```tsx
+const [search, setSearch] = useState("");
+const [page, setPage] = useState(0);
+const { data, isFetching } = useQuery({
+  queryKey: ["people", search, page],
+  queryFn: ({ signal }) => fetchPeople({ search, page, signal }),
+  placeholderData: keepPreviousData,
+});
+
+<MultiSelect
+  mode="server"
+  options={data?.options ?? []}
+  hasMore={data?.hasMore}
+  loading={isFetching}
+  onSearchChange={(term) => { setPage(0); setSearch(term); }}
+  onLoadMore={() => setPage((p) => p + 1)}
+  value={selected}
+  onChange={setSelected}
+/>;
+```
+
+- `onSearchChange` fires once when the list opens (so you can load a first page)
+  and then debounced as the user types.
+- Labels of chosen options are remembered, so tags stay readable after the
+  results change. If you set `value` from outside before the matching options
+  have loaded, the raw value is shown until they arrive.
+
+## Keyboard
+
+| Keys | Action |
+| --- | --- |
+| **Enter**, **Space**, **↓**, **↑** | Open the list. |
+| **↓** / **↑** | Move between options (disabled options are skipped). |
+| **Home** / **End** | First / last option. |
+| **Page Down** / **Page Up** | Move ten options. |
+| **Enter** | Choose the highlighted option, or create. |
+| **Escape** | Close and return focus to the control. |
+| **Tab** | Close and move to the next field. |
+| **Backspace** | MultiSelect: remove the last tag (when the search box is empty). |
+| typing | Types into the search box, or jumps to a matching option when `searchable={false}`. |
+
+The control is a `role="combobox"` that owns a `role="listbox"`; the active
+option is tracked with `aria-activedescendant`, so focus stays in the search
+box. The list renders in the top layer through the native Popover API, so it is
+never clipped by a scrolling parent (including inside a DataGrid cell).
+
+## Theming
+
+Override `--cb-*` variables (they default to the grid's `--dg-*`):
+
+```css
+.cb-root { --cb-accent: #7c3aed; --cb-radius: 12px; }
+```
+
+State attributes for styling: `data-state="open"`, `data-size`, `data-invalid`,
+`data-disabled` on the root and control; `data-active`, `data-selected`,
+`data-disabled` on options.
+
+## Headless use
+
+`useCombobox()` holds the whole engine (filtering, active option, keyboard,
+selection, search requests) and is exported if you want to build a different UI
+on top. The framework-free helpers — `filterOptions`, `buildListItems`,
+`nextEnabledIndex`, `toggleValue`, `measureItems`, `getVisibleRange` — are
+exported from `@/components/combobox/core` and can also run on a server.
+
+## Known limits
+
+- Option rows have a fixed height per `size` (taller when any option has a
+  description), because the list is virtualized.
+- No async "load option by value": pass options that include the selected
+  values, or select them through the UI at least once.
+- Tree or multi-level options are not supported.