gbs-add-block 1.2.16 → 1.2.17

package/source/beta-components/card/styles.css

@@ -0,0 +1,231 @@
+/*
+ * Card and Stat styles.
+ *
+ * Tokens read the shared --gbs-* variables when they are set on an ancestor
+ * (set them on :root to theme every component at once) and fall back to the
+ * same default palette otherwise. Rules live in the `components` layer, so utility classes passed
+ * through `className` / `classNames` override them.
+ */
+@layer theme, base, components, utilities;
+
+@layer components {
+  .cd-root,
+  .st-root {
+    --cd-bg: var(--gbs-bg, var(--dg-bg, light-dark(#ffffff, #0b0b0e)));
+    --cd-fg: var(--gbs-fg, var(--dg-fg, light-dark(#18181b, #f4f4f5)));
+    --cd-muted: var(--gbs-muted, var(--dg-muted, light-dark(#71717a, #a1a1aa)));
+    --cd-border: var(--gbs-border, var(--dg-border, light-dark(#e4e4e7, #27272a)));
+    --cd-hover: var(--gbs-hover, var(--dg-hover, light-dark(#f4f4f5, #1f1f23)));
+    --cd-focus: var(--gbs-focus, var(--dg-focus, light-dark(#2563eb, #60a5fa)));
+    --cd-success: var(--gbs-success, light-dark(#15803d, #4ade80));
+    --cd-danger: var(--gbs-danger, var(--dg-danger, light-dark(#dc2626, #f87171)));
+    --cd-shadow: var(--gbs-shadow, var(--dg-shadow, 0 10px 30px -8px light-dark(rgb(0 0 0 / 0.18), rgb(0 0 0 / 0.6))));
+    --cd-radius: var(--gbs-radius, var(--dg-radius, 8px));
+    --cd-font-size: var(--gbs-font-size, var(--dg-font-size, 13px));
+    --cd-px: 16px;
+
+    color-scheme: inherit;
+    font-size: var(--cd-font-size);
+    line-height: 1.5;
+    color: var(--cd-fg);
+  }
+
+  :where(.dark, [data-theme="dark"]) :is(.cd-root, .st-root) {
+    color-scheme: dark;
+  }
+  :where(.light, [data-theme="light"]) :is(.cd-root, .st-root) {
+    color-scheme: light;
+  }
+
+  :where(.cd-root, .st-root) *,
+  :where(.cd-root, .st-root) *::before,
+  :where(.cd-root, .st-root) *::after {
+    box-sizing: border-box;
+  }
+
+  /* ---------------------------------------------------------------- card */
+
+  .cd-root {
+    display: flex;
+    flex-direction: column;
+    min-width: 0;
+    border-radius: var(--cd-radius);
+    background: var(--cd-bg);
+    text-decoration: none;
+  }
+  .cd-root[data-variant="outlined"] {
+    border: 1px solid var(--cd-border);
+  }
+  .cd-root[data-variant="elevated"] {
+    border: 1px solid transparent;
+    box-shadow: var(--cd-shadow);
+  }
+  .cd-root[data-variant="plain"] {
+    background: transparent;
+  }
+
+  .cd-root[data-padding="none"] {
+    --cd-px: 0px;
+  }
+  .cd-root[data-padding="sm"] {
+    --cd-px: 12px;
+  }
+  .cd-root[data-padding="lg"] {
+    --cd-px: 24px;
+  }
+
+  .cd-root[data-interactive] {
+    cursor: pointer;
+    transition:
+      background-color 120ms ease,
+      box-shadow 120ms ease,
+      translate 120ms ease;
+  }
+  .cd-root[data-interactive]:hover {
+    background: var(--cd-hover);
+  }
+  .cd-root[data-variant="elevated"][data-interactive]:hover {
+    translate: 0 -1px;
+  }
+  .cd-root[data-interactive]:focus-visible {
+    outline: 2px solid var(--cd-focus);
+    outline-offset: 2px;
+  }
+
+  .cd-header {
+    display: flex;
+    align-items: flex-start;
+    gap: 12px;
+    padding: var(--cd-px) var(--cd-px) 0;
+  }
+  .cd-heading {
+    flex: 1 1 auto;
+    min-width: 0;
+  }
+  .cd-title {
+    font-size: 1.05em;
+    font-weight: 600;
+    line-height: 1.35;
+  }
+  .cd-description {
+    margin-top: 2px;
+    color: var(--cd-muted);
+  }
+  .cd-actions {
+    display: flex;
+    flex: none;
+    align-items: center;
+    gap: 4px;
+  }
+
+  .cd-body {
+    flex: 1 1 auto;
+    min-width: 0;
+    padding: var(--cd-px);
+  }
+  /* The header already spaces the top, so the body should not double it. */
+  .cd-header + .cd-body {
+    padding-top: 12px;
+  }
+
+  .cd-footer {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    gap: 8px;
+    padding: 12px var(--cd-px);
+    border-top: 1px solid var(--cd-border);
+  }
+
+  /* ---------------------------------------------------------------- stat */
+
+  .st-root {
+    display: flex;
+    flex-direction: column;
+    gap: 4px;
+    min-width: 0;
+  }
+  .st-head {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+  }
+  .st-label {
+    flex: 1 1 auto;
+    min-width: 0;
+    color: var(--cd-muted);
+    font-weight: 500;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+  .st-icon {
+    display: inline-flex;
+    flex: none;
+    color: var(--cd-muted);
+  }
+  .st-value {
+    font-size: 1.9em;
+    font-weight: 650;
+    font-variant-numeric: tabular-nums;
+    line-height: 1.15;
+    letter-spacing: -0.01em;
+  }
+
+  .st-trend {
+    display: flex;
+    align-items: center;
+    gap: 4px;
+    color: var(--cd-muted);
+  }
+  /* Colour is a second signal: the arrow and the visually hidden word carry
+     the direction on their own. */
+  .st-trend[data-positive="true"] {
+    color: var(--cd-success);
+  }
+  .st-trend[data-positive="false"] {
+    color: var(--cd-danger);
+  }
+  .st-trend-label {
+    font-variant-numeric: tabular-nums;
+    font-weight: 500;
+  }
+  .st-trend-description {
+    color: var(--cd-muted);
+  }
+
+  .st-help {
+    color: var(--cd-muted);
+  }
+
+  .st-placeholder {
+    border-radius: 4px;
+    background: var(--cd-hover);
+  }
+  .st-placeholder-value {
+    width: 5ch;
+    height: 1.9em;
+  }
+  .st-placeholder-help {
+    width: 10ch;
+    height: 1em;
+  }
+
+  .st-sr-only {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    margin: -1px;
+    padding: 0;
+    overflow: hidden;
+    border: 0;
+    clip-path: inset(50%);
+    white-space: nowrap;
+  }
+
+  @media (forced-colors: active) {
+    .cd-root[data-variant="elevated"] {
+      border-color: CanvasText;
+    }
+  }
+}

package/source/beta-components/menu/README.md

@@ -0,0 +1,68 @@
+# Menu
+
+A menu of commands for React 19, following the WAI-ARIA menu button pattern. No
+runtime dependencies besides React.
+
+```ts
+import {
+  Menu, MenuItem, MenuCheckboxItem, MenuRadioGroup, MenuRadioItem,
+  MenuGroup, MenuSeparator, MenuSub,
+} from "@/components/menu";
+import "@/components/menu/styles.css";
+```
+
+```tsx
+<Menu trigger={<Button variant="outline">Actions</Button>} label="Row actions">
+  <MenuItem icon={<EditIcon />} shortcut="⌘E" onSelect={edit}>Edit</MenuItem>
+  <MenuSub label="Export">
+    <MenuItem onSelect={() => download("csv")}>CSV</MenuItem>
+    <MenuItem onSelect={() => download("pdf")}>PDF</MenuItem>
+  </MenuSub>
+  <MenuSeparator />
+  <MenuCheckboxItem checked={compact} onCheckedChange={setCompact}>Compact rows</MenuCheckboxItem>
+  <MenuSeparator />
+  <MenuItem destructive onSelect={remove}>Delete</MenuItem>
+</Menu>
+```
+
+| Prop | Default | Description |
+| --- | --- | --- |
+| `trigger` | — | A single element, cloned with the ARIA wiring. |
+| `open` / `defaultOpen` / `onOpenChange` | — | Controlled or uncontrolled. Reasons: `escape`, `outside`, `trigger`, `select`, `api`. |
+| `label` | "Menu" | Names the menu for screen readers. |
+| `side` / `align` / `gap` | `bottom` / `start` / `4` | Flips and clamps to stay on screen. |
+| `closeOnSelect` | `true` | Whether choosing an item closes the menu. |
+| `className`, `classNames`, `style`, `localeText` | — | Slots: `root`, `list`, `item`, `icon`, `label`, `shortcut`, `separator`, `group`, `groupLabel`, `indicator`, `submenu`. |
+
+## Items
+
+| Component | Notes |
+| --- | --- |
+| `MenuItem` | `onSelect`, `icon`, `shortcut`, `disabled`, `destructive`. Closes the menu by default. |
+| `MenuCheckboxItem` | `checked` / `onCheckedChange`. Stays open by default, so several can be toggled. |
+| `MenuRadioGroup` + `MenuRadioItem` | `value` / `onValueChange` on the group, `value` on each item. |
+| `MenuGroup` | A titled section; the title is a label, never focused. |
+| `MenuSeparator` | A rule between sections. |
+| `MenuSub` | A nested menu, opened by hover, Enter or the arrow pointing into it. |
+
+`shortcut` only draws the hint — binding the key is yours, because only the page
+knows what else is listening.
+
+## Keyboard
+
+| Key | Does |
+| --- | --- |
+| `ArrowDown` / `ArrowUp` on the trigger | Opens, starting at the first or last item. |
+| `ArrowDown` / `ArrowUp` | Moves through items, wrapping, skipping disabled ones. |
+| `Home` / `End` | First / last item. |
+| Letters | Typeahead. Repeating a letter cycles through items starting with it. |
+| `Enter` / `Space` | Chooses the focused item. |
+| `ArrowRight` / `ArrowLeft` | Opens a submenu / goes back to its parent (mirrored in RTL). |
+| `Escape` | Closes and returns focus to the trigger. |
+| `Tab` | Closes and carries on through the page. |
+
+Disabled items stay focusable so that someone navigating by keyboard can find
+out an action exists but is unavailable; arrow keys skip past them.
+
+The navigation and typeahead rules are framework-free in `core/navigation.ts`
+and unit-tested there. Placement comes from `shared/core/position.ts`.

package/source/beta-components/menu/__tests__/core.test.ts

@@ -0,0 +1,120 @@
+import { describe, expect, it } from "vitest";
+import {
+  edgeIndex,
+  isTypeaheadKey,
+  nextIndex,
+  typeaheadBuffer,
+  typeaheadIndex,
+} from "../core/navigation";
+
+const items = (...text: string[]) => text.map((label) => ({ text: label }));
+
+const withDisabled = [
+  { text: "Cut" },
+  { text: "Copy", disabled: true },
+  { text: "Paste" },
+  { text: "Paste special", disabled: true },
+];
+
+describe("nextIndex", () => {
+  it("steps forwards and backwards", () => {
+    const list = items("a", "b", "c");
+    expect(nextIndex(list, 0, 1)).toBe(1);
+    expect(nextIndex(list, 2, -1)).toBe(1);
+  });
+
+  it("wraps around, which is what a menu does", () => {
+    const list = items("a", "b", "c");
+    expect(nextIndex(list, 2, 1)).toBe(0);
+    expect(nextIndex(list, 0, -1)).toBe(2);
+  });
+
+  it("skips disabled items in both directions", () => {
+    expect(nextIndex(withDisabled, 0, 1)).toBe(2);
+    expect(nextIndex(withDisabled, 2, -1)).toBe(0);
+  });
+
+  it("starts at the near end when nothing is focused", () => {
+    const list = items("a", "b", "c");
+    expect(nextIndex(list, -1, 1)).toBe(0);
+    expect(nextIndex(list, -1, -1)).toBe(2);
+  });
+
+  it("gives up rather than landing on a disabled item", () => {
+    expect(nextIndex([{ text: "only", disabled: true }], 0, 1)).toBe(-1);
+    expect(nextIndex([], 0, 1)).toBe(-1);
+  });
+});
+
+describe("edgeIndex", () => {
+  it("finds the first and last item that can be focused", () => {
+    expect(edgeIndex(withDisabled, "first")).toBe(0);
+    expect(edgeIndex(withDisabled, "last")).toBe(2);
+  });
+
+  it("is -1 when nothing can be focused", () => {
+    expect(edgeIndex([{ text: "x", disabled: true }], "first")).toBe(-1);
+  });
+});
+
+describe("typeaheadIndex", () => {
+  const list = items("Save", "Save as", "Send", "Print");
+
+  it("jumps to the first item starting with the letter", () => {
+    expect(typeaheadIndex(list, "p", 0)).toBe(3);
+  });
+
+  it("ignores case and leading space", () => {
+    expect(typeaheadIndex(list, "  SE", 0)).toBe(2);
+  });
+
+  it("cycles through items sharing a letter when it is repeated", () => {
+    expect(typeaheadIndex(list, "s", -1)).toBe(0);
+    expect(typeaheadIndex(list, "ss", 0)).toBe(1);
+    expect(typeaheadIndex(list, "sss", 1)).toBe(2);
+    // …and back round to the first.
+    expect(typeaheadIndex(list, "ssss", 2)).toBe(0);
+  });
+
+  it("treats a longer string as a prefix, refining from where it is", () => {
+    expect(typeaheadIndex(list, "save a", 0)).toBe(1);
+  });
+
+  it("stays put when nothing matches", () => {
+    expect(typeaheadIndex(list, "z", 0)).toBe(-1);
+    expect(typeaheadIndex(list, "", 0)).toBe(-1);
+  });
+
+  it("never lands on a disabled item", () => {
+    // Only the disabled "Copy" starts with "co", so focus stays where it is.
+    expect(typeaheadIndex(withDisabled, "co", 0)).toBe(-1);
+    // "c" also matches the enabled "Cut", which it wraps round to find.
+    expect(typeaheadIndex(withDisabled, "c", 0)).toBe(0);
+  });
+});
+
+describe("typeaheadBuffer", () => {
+  it("builds a word from keys typed in quick succession", () => {
+    expect(typeaheadBuffer("s", "a", 120)).toBe("sa");
+  });
+
+  it("starts again after a pause", () => {
+    expect(typeaheadBuffer("sa", "p", 900)).toBe("p");
+  });
+});
+
+describe("isTypeaheadKey", () => {
+  it("takes printable characters", () => {
+    expect(isTypeaheadKey("a", false)).toBe(true);
+    expect(isTypeaheadKey("7", false)).toBe(true);
+  });
+
+  it("leaves Space alone, since it chooses an item", () => {
+    expect(isTypeaheadKey(" ", false)).toBe(false);
+  });
+
+  it("ignores named keys and anything with a modifier", () => {
+    expect(isTypeaheadKey("ArrowDown", false)).toBe(false);
+    expect(isTypeaheadKey("a", true)).toBe(false);
+  });
+});

package/source/beta-components/menu/core/index.ts

@@ -0,0 +1,11 @@
+// Framework-free: roving focus and typeahead, with no DOM involved.
+export {
+  edgeIndex,
+  isTypeaheadKey,
+  nextIndex,
+  typeaheadBuffer,
+  typeaheadIndex,
+  TYPEAHEAD_RESET_MS,
+} from "./navigation";
+export type { NavigableItem } from "./navigation";
+export type * from "./types";

package/source/beta-components/menu/core/navigation.ts

@@ -0,0 +1,84 @@
+/** How long a run of keystrokes counts as one word for typeahead. */
+export const TYPEAHEAD_RESET_MS = 700;
+
+export interface NavigableItem {
+  /** Disabled items are skipped by the keyboard, as WAI-ARIA's menu pattern allows. */
+  disabled?: boolean;
+  /** The visible text, lowercased by the caller or not — matching ignores case. */
+  text?: string;
+}
+
+/**
+ * The next item to focus from `from`, stepping by `step` and skipping disabled
+ * items. Wraps around, which is what a menu does and a listbox does not.
+ *
+ * Returns -1 when every item is disabled, so callers can leave focus alone
+ * rather than moving it somewhere meaningless.
+ */
+export function nextIndex(items: readonly NavigableItem[], from: number, step: number): number {
+  if (items.length === 0) return -1;
+  // Nothing focused yet: Down starts at the top, Up at the bottom.
+  if (from < 0) return edgeIndex(items, step > 0 ? "first" : "last");
+  for (let moved = 1; moved <= items.length; moved += 1) {
+    const index = (from + step * moved + items.length * moved) % items.length;
+    if (!items[index]?.disabled) return index;
+  }
+  return -1;
+}
+
+/** The first or last item that can be focused. */
+export function edgeIndex(items: readonly NavigableItem[], edge: "first" | "last"): number {
+  const order = edge === "first" ? items.keys() : [...items.keys()].reverse();
+  for (const index of order) {
+    if (!items[index]?.disabled) return index;
+  }
+  return -1;
+}
+
+/**
+ * The item a typed string should jump to, searching from just after `from` and
+ * wrapping, so repeating a letter cycles through the items starting with it.
+ *
+ * Returns -1 when nothing matches, leaving focus where it is rather than
+ * jumping somewhere unrelated.
+ */
+export function typeaheadIndex(
+  items: readonly NavigableItem[],
+  query: string,
+  from: number,
+): number {
+  const needle = query.trim().toLowerCase();
+  if (!needle) return -1;
+
+  // A repeated single letter cycles; anything longer is a prefix search from
+  // the current item, so "sa" after "s" refines instead of jumping on.
+  const repeated = needle.length > 1 && [...needle].every((character) => character === needle[0]);
+  const search = repeated ? needle[0] : needle;
+  const start = repeated || needle.length === 1 ? from + 1 : from;
+
+  for (let offset = 0; offset < items.length; offset += 1) {
+    const index = (start + offset + items.length) % items.length;
+    const item = items[index];
+    if (item?.disabled) continue;
+    if ((item?.text ?? "").trim().toLowerCase().startsWith(search)) return index;
+  }
+  return -1;
+}
+
+/**
+ * Collects the buffer for typeahead: keystrokes within `TYPEAHEAD_RESET_MS` of
+ * each other build a word, and a longer pause starts a new one.
+ */
+export function typeaheadBuffer(
+  previous: string,
+  key: string,
+  elapsedMs: number,
+  resetMs: number = TYPEAHEAD_RESET_MS,
+): string {
+  return elapsedMs > resetMs ? key : previous + key;
+}
+
+/** Whether a key should be added to the typeahead buffer rather than handled. */
+export function isTypeaheadKey(key: string, modified: boolean): boolean {
+  return !modified && key.length === 1 && key !== " " && /\S/.test(key);
+}

package/source/beta-components/menu/core/types.ts

@@ -0,0 +1,32 @@
+import type { ReactNode } from "react";
+
+export type MenuSide = "top" | "bottom" | "left" | "right";
+export type MenuAlign = "start" | "end";
+
+/** What closed the menu, so callers can tell a choice from a dismissal. */
+export type MenuCloseReason = "escape" | "outside" | "trigger" | "select" | "api";
+
+export type MenuSlot =
+  | "root"
+  | "list"
+  | "item"
+  | "icon"
+  | "label"
+  | "shortcut"
+  | "separator"
+  | "group"
+  | "groupLabel"
+  | "indicator"
+  | "submenu";
+
+export interface MenuLocaleText {
+  /** Fallback name for a menu with no label. */
+  label: string;
+  /** Announced on a submenu trigger. */
+  submenu(label: string): string;
+}
+
+/** A shortcut shown beside an item. Purely a hint: the menu does not bind keys. */
+export interface MenuShortcut {
+  keys: ReactNode;
+}

package/source/beta-components/menu/index.ts

@@ -0,0 +1,19 @@
+export { Menu, MenuSub } from "./react/Menu";
+export type { MenuHandle, MenuProps, MenuSubProps } from "./react/Menu";
+export {
+  MenuCheckboxItem,
+  MenuGroup,
+  MenuItem,
+  MenuRadioGroup,
+  MenuRadioItem,
+  MenuSeparator,
+} from "./react/items";
+export type {
+  MenuCheckboxItemProps,
+  MenuGroupProps,
+  MenuItemProps,
+  MenuRadioGroupProps,
+  MenuRadioItemProps,
+} from "./react/items";
+export { defaultMenuText } from "./react/locale";
+export * from "./core";