@elabs-ai/components-ui 4.0.0 → 4.1.0

package/src/components/keyboard-shortcuts/keyboard-shortcuts.stories.tsx

@@ -0,0 +1,177 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect } from "storybook/test";
+import { useState } from "react";
+import { KeyboardShortcuts, type ShortcutGroup } from "./keyboard-shortcuts";
+
+const groups: ShortcutGroup[] = [
+  {
+    id: "navigation",
+    label: "Navigation",
+    defaultOpen: true,
+    items: [
+      { action: "Open command palette", keys: ["⌘", "K"] },
+      { action: "Go to file", keys: ["⌘", "P"] },
+      { action: "Go to line", keys: ["⌘", "G"] },
+    ],
+  },
+  {
+    id: "general",
+    label: "General",
+    items: [
+      { action: "Close tab", keys: ["⌘", "W"] },
+      { action: "Save", keys: ["⌘", "S"] },
+      { action: "New window", keys: ["⌘", "⇧", "N"] },
+    ],
+  },
+  {
+    id: "editing",
+    label: "Editing",
+    items: [
+      { action: "Duplicate line", keys: ["⌘", "⇧", "D"] },
+      { action: "Comment line", keys: ["⌘", "/"] },
+    ],
+  },
+];
+
+const meta = {
+  title: "Disclosure/KeyboardShortcuts",
+  component: KeyboardShortcuts,
+  tags: ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "A grouped, searchable presentation of a shortcut set. Renders content only — " +
+          "the app supplies the Dialog/Sheet shell, so the same component works in a modal, " +
+          "a settings page or a sidebar. Group counts are always derived from `items.length` " +
+          "(or the number of matching items while filtering), never passed in.",
+      },
+    },
+  },
+  argTypes: {
+    groups: {
+      description:
+        "Shortcut groups (`ShortcutGroup[]`). Each group's displayed count is derived from `items.length`.",
+      control: false,
+      table: { category: "Content" },
+    },
+    searchable: {
+      description: "Show the built-in search field.",
+      control: "boolean",
+      table: { category: "Behavior" },
+    },
+    query: {
+      description: "Controlled search query, if the app owns it.",
+      control: "text",
+      table: { category: "State" },
+    },
+    onQueryChange: {
+      description: "Callback fired when the search query changes.",
+      control: false,
+      table: { category: "Behavior" },
+    },
+    className: {
+      description: "Extra Tailwind classes merged via cn().",
+      control: "text",
+      table: { category: "Appearance" },
+    },
+  },
+  args: {
+    groups,
+  },
+} satisfies Meta<typeof KeyboardShortcuts>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    groups,
+  },
+  render: (args) => (
+    <div className="w-96">
+      <KeyboardShortcuts {...args} />
+    </div>
+  ),
+};
+
+/** Typing a query hides non-matching groups and re-derives the visible group's count. */
+export const Filtered: Story = {
+  args: {
+    groups,
+  },
+  render: (args) => (
+    <div className="w-96">
+      <KeyboardShortcuts {...args} query="close" />
+    </div>
+  ),
+  play: async ({ canvas }) => {
+    // Only "General" contains a "Close tab" action — the other two groups hide entirely.
+    await expect(canvas.getByText("General")).toBeInTheDocument();
+    await expect(canvas.queryByText("Navigation")).not.toBeInTheDocument();
+    await expect(canvas.queryByText("Editing")).not.toBeInTheDocument();
+    // The visible group's badge reflects the single matching item, not its total (3).
+    await expect(canvas.getByText("1")).toBeInTheDocument();
+    await expect(canvas.getByText("Close tab")).toBeInTheDocument();
+  },
+};
+
+/** A query that matches nothing renders a designed empty message, not a blank area. */
+export const NoMatches: Story = {
+  args: {
+    groups,
+  },
+  render: (args) => (
+    <div className="w-96">
+      <KeyboardShortcuts {...args} query="xyz-nonexistent" />
+    </div>
+  ),
+  play: async ({ canvas }) => {
+    await expect(canvas.getByText("No shortcuts found")).toBeInTheDocument();
+  },
+};
+
+/** Uncontrolled search — the app doesn't own the query; the component manages it internally. */
+export const Uncontrolled: Story = {
+  args: {
+    groups,
+  },
+  render: (args) => (
+    <div className="w-96">
+      <KeyboardShortcuts {...args} />
+    </div>
+  ),
+  play: async ({ canvas, userEvent }) => {
+    const input = canvas.getByLabelText("Search shortcuts");
+    await userEvent.type(input, "save");
+    await expect(canvas.getByText("General")).toBeInTheDocument();
+    await expect(canvas.queryByText("Navigation")).not.toBeInTheDocument();
+  },
+};
+
+/** The app owns the query — e.g. it lives alongside a `Dialog` header search field. */
+export const ControlledQuery: Story = {
+  render: () => {
+    function Demo() {
+      const [query, setQuery] = useState("");
+      return (
+        <div className="w-96">
+          <KeyboardShortcuts groups={groups} query={query} onQueryChange={setQuery} />
+        </div>
+      );
+    }
+    return <Demo />;
+  },
+};
+
+/** No search field — just the grouped, collapsible list. */
+export const NotSearchable: Story = {
+  args: {
+    groups,
+    searchable: false,
+  },
+  render: (args) => (
+    <div className="w-96">
+      <KeyboardShortcuts {...args} />
+    </div>
+  ),
+};

package/src/components/keyboard-shortcuts/keyboard-shortcuts.test.tsx

@@ -0,0 +1,73 @@
+import { describe, expect, it } from "vitest";
+import { render, screen } from "@testing-library/react";
+import { KeyboardShortcuts, type ShortcutGroup } from "./keyboard-shortcuts";
+
+const groups: ShortcutGroup[] = [
+  {
+    id: "navigation",
+    label: "Navigation",
+    items: [
+      { action: "Open command palette", keys: ["⌘", "K"] },
+      { action: "Go to file", keys: ["⌘", "P"] },
+    ],
+  },
+  {
+    id: "general",
+    label: "General",
+    items: [
+      { action: "Close tab", keys: ["⌘", "W"] },
+      { action: "Save", keys: ["⌘", "S"] },
+      { action: "New window", keys: ["⌘", "⇧", "N"] },
+    ],
+  },
+];
+
+describe("KeyboardShortcuts", () => {
+  it("renders every group with a count derived from items.length", () => {
+    render(<KeyboardShortcuts groups={groups} searchable={false} />);
+    expect(screen.getByText("Navigation")).toBeInTheDocument();
+    expect(screen.getByText("General")).toBeInTheDocument();
+    // "Navigation" has 2 items, "General" has 3 — neither count was passed in.
+    expect(screen.getByText("2")).toBeInTheDocument();
+    expect(screen.getByText("3")).toBeInTheDocument();
+  });
+
+  it("a query matching only one group hides the others, and derives the visible group's count from the matches", () => {
+    render(<KeyboardShortcuts groups={groups} query="close" />);
+
+    // Only "General" has an item matching "close" — "Navigation" is hidden entirely,
+    // not rendered empty.
+    expect(screen.getByText("General")).toBeInTheDocument();
+    expect(screen.queryByText("Navigation")).not.toBeInTheDocument();
+
+    // The visible group's displayed count is the number of MATCHING items (1),
+    // never its total item count (3) — this is the "count is derived" lock.
+    expect(screen.getByText("1")).toBeInTheDocument();
+    expect(screen.queryByText("3")).not.toBeInTheDocument();
+    expect(screen.getByText("Close tab")).toBeInTheDocument();
+  });
+
+  it("matches on key tokens as well as action text", () => {
+    render(<KeyboardShortcuts groups={groups} query="⇧" />);
+    expect(screen.getByText("General")).toBeInTheDocument();
+    expect(screen.queryByText("Navigation")).not.toBeInTheDocument();
+    expect(screen.getByText("New window")).toBeInTheDocument();
+  });
+
+  it("renders a designed empty message, not a blank area, when nothing matches", () => {
+    render(<KeyboardShortcuts groups={groups} query="does-not-exist" />);
+    expect(screen.queryByText("Navigation")).not.toBeInTheDocument();
+    expect(screen.queryByText("General")).not.toBeInTheDocument();
+    expect(screen.getByText("No shortcuts found")).toBeInTheDocument();
+  });
+
+  it("supports an uncontrolled query without a query prop", () => {
+    render(<KeyboardShortcuts groups={groups} />);
+    expect(screen.getByLabelText("Search shortcuts")).toHaveValue("");
+  });
+
+  it("renders no search field when searchable is false", () => {
+    render(<KeyboardShortcuts groups={groups} searchable={false} />);
+    expect(screen.queryByLabelText("Search shortcuts")).not.toBeInTheDocument();
+  });
+});

package/src/components/keyboard-shortcuts/keyboard-shortcuts.tsx

@@ -0,0 +1,203 @@
+"use client";
+
+import { forwardRef, useId, useMemo, useState, type ComponentProps } from "react";
+import { ChevronDown, Search } from "lucide-react";
+import { cn } from "../../lib/cn";
+import { Badge } from "../badge";
+import { Collapsible, CollapsibleContent, CollapsibleTrigger } from "../collapsible";
+import { Input } from "../input";
+import { Kbd } from "../kbd";
+import { useLocale } from "../locale-provider";
+import { StatePanel } from "../state-panel";
+
+/** One keyboard shortcut: the action it performs and its ordered key tokens. */
+export interface Shortcut {
+  action: string;
+  /** Ordered key tokens, e.g. `["⌘", "K"]`. Rendered via {@link Kbd}. */
+  keys: string[];
+}
+
+/**
+ * A named group of shortcuts. There is deliberately no `count` field — the
+ * displayed count is always derived from `items.length`, never supplied by
+ * the caller (see issue #113: brainless, the upstream this was adapted from,
+ * shipped a `count` with no `items`, an honestly-unverifiable number).
+ */
+export interface ShortcutGroup {
+  id: string;
+  label: string;
+  items: Shortcut[];
+  /** Whether this group starts expanded when search is inactive. @default false */
+  defaultOpen?: boolean;
+}
+
+export interface KeyboardShortcutsProps extends Omit<ComponentProps<"div">, "onChange"> {
+  groups: ShortcutGroup[];
+  /** Show the built-in search field. @default true */
+  searchable?: boolean;
+  /** Controlled search query, if the app owns it. */
+  query?: string;
+  onQueryChange?: (query: string) => void;
+}
+
+function matchesQuery(shortcut: Shortcut, normalizedQuery: string): boolean {
+  if (shortcut.action.toLowerCase().includes(normalizedQuery)) return true;
+  return shortcut.keys.some((key) => key.toLowerCase().includes(normalizedQuery));
+}
+
+interface FilteredGroup {
+  group: ShortcutGroup;
+  items: Shortcut[];
+}
+
+/**
+ * A grouped, searchable presentation of a shortcut set. Renders **content
+ * only** — the app supplies the `Dialog`/`Sheet` shell, so the same
+ * component works in a modal, a settings page or a sidebar.
+ *
+ * Group counts are always derived from `items.length` (or the number of
+ * matching items while a search is active) — never a value passed in.
+ */
+export const KeyboardShortcuts = forwardRef<HTMLDivElement, KeyboardShortcutsProps>(
+  function KeyboardShortcuts(
+    { groups, searchable = true, query: queryProp, onQueryChange, className, ...props },
+    ref,
+  ) {
+    const isControlled = queryProp !== undefined;
+    const [internalQuery, setInternalQuery] = useState("");
+    const query = isControlled ? queryProp : internalQuery;
+    const normalizedQuery = query.trim().toLowerCase();
+    const isFiltering = normalizedQuery.length > 0;
+    const { t } = useLocale();
+    const searchId = useId();
+
+    const setQuery = (next: string) => {
+      if (!isControlled) setInternalQuery(next);
+      onQueryChange?.(next);
+    };
+
+    const filteredGroups = useMemo<FilteredGroup[]>(() => {
+      return groups
+        .map((group) => ({
+          group,
+          items: isFiltering
+            ? group.items.filter((item) => matchesQuery(item, normalizedQuery))
+            : group.items,
+        }))
+        .filter(({ items }) => items.length > 0);
+    }, [groups, isFiltering, normalizedQuery]);
+
+    return (
+      <div
+        ref={ref}
+        data-slot="keyboard-shortcuts"
+        className={cn("flex flex-col gap-4", className)}
+        {...props}
+      >
+        {searchable && (
+          <div data-slot="keyboard-shortcuts-search" className="relative">
+            <label htmlFor={searchId} className="sr-only">
+              Search shortcuts
+            </label>
+            <Search
+              aria-hidden="true"
+              className="pointer-events-none absolute left-2.5 top-1/2 size-4 -translate-y-1/2 text-muted-foreground"
+            />
+            <Input
+              id={searchId}
+              type="search"
+              autoComplete="off"
+              placeholder={t("ui.keyboardShortcuts.searchPlaceholder")}
+              value={query}
+              onChange={(event) => setQuery(event.target.value)}
+              className="pl-8"
+            />
+          </div>
+        )}
+
+        {filteredGroups.length === 0 ? (
+          <div data-slot="keyboard-shortcuts-empty">
+            <StatePanel
+              kind="empty"
+              title={t("ui.keyboardShortcuts.emptyTitle")}
+              description={
+                isFiltering
+                  ? t("ui.keyboardShortcuts.emptyFiltered", { query: query.trim() })
+                  : t("ui.keyboardShortcuts.empty")
+              }
+            />
+          </div>
+        ) : (
+          <div data-slot="keyboard-shortcuts-groups" className="flex flex-col gap-2">
+            {filteredGroups.map(({ group, items }) => (
+              <ShortcutGroupItem
+                key={group.id}
+                group={group}
+                items={items}
+                forceOpen={isFiltering}
+              />
+            ))}
+          </div>
+        )}
+      </div>
+    );
+  },
+);
+
+interface ShortcutGroupItemProps {
+  group: ShortcutGroup;
+  /** Items to display — the full group, or the subset matching the active search. */
+  items: Shortcut[];
+  /** Force the group open (search is active) without discarding the user's manual toggle. */
+  forceOpen: boolean;
+}
+
+function ShortcutGroupItem({ group, items, forceOpen }: ShortcutGroupItemProps) {
+  const [open, setOpen] = useState(group.defaultOpen ?? false);
+
+  return (
+    <Collapsible
+      data-slot="keyboard-shortcuts-group"
+      open={forceOpen || open}
+      onOpenChange={setOpen}
+      className="rounded-md border"
+    >
+      <CollapsibleTrigger
+        data-slot="keyboard-shortcuts-group-trigger"
+        className={cn(
+          "flex w-full items-center justify-between gap-2 rounded-md px-3 py-2 text-start",
+          "focus-ring",
+          "[&[data-state=open]>svg]:rotate-180",
+        )}
+      >
+        <span className="flex items-center gap-2">
+          <span className="text-body font-medium text-foreground">{group.label}</span>
+          {/* Derived from items.length — never a caller-supplied count (see #113). */}
+          <Badge variant="secondary">{items.length}</Badge>
+        </span>
+        <ChevronDown
+          aria-hidden="true"
+          className="size-4 shrink-0 text-muted-foreground transition-transform duration-base ease-standard"
+        />
+      </CollapsibleTrigger>
+      <CollapsibleContent data-slot="keyboard-shortcuts-group-content">
+        <ul className="flex flex-col gap-1 px-3 pb-3">
+          {items.map((item, index) => (
+            <li
+              key={`${item.action}-${index}`}
+              data-slot="keyboard-shortcuts-item"
+              className="flex items-center justify-between gap-4 py-1"
+            >
+              <span className="text-body text-muted-foreground">{item.action}</span>
+              <span className="flex items-center gap-1">
+                {item.keys.map((key, keyIndex) => (
+                  <Kbd key={`${key}-${keyIndex}`}>{key}</Kbd>
+                ))}
+              </span>
+            </li>
+          ))}
+        </ul>
+      </CollapsibleContent>
+    </Collapsible>
+  );
+}

package/src/components/link-preview/link-preview.tsx

@@ -115,7 +115,7 @@ export const LinkPreviewCard = forwardRef<HTMLDivElement, LinkPreviewCardProps>(
           // When `href` is present: stretched-link focus ring (via focus-within on
           // the container, not the <a>) + hover lift + motion-tokened transition.
           href &&
-            "cursor-pointer transition-[translate,box-shadow,border-color] duration-fast ease-standard focus-within:outline-none focus-within:ring-2 focus-within:ring-ring hover:-translate-y-0.5 hover:border-ring/40 hover:shadow-md motion-reduce:hover:translate-y-0",
+            "cursor-pointer transition-[translate,box-shadow,border-color] duration-fast ease-standard focus-ring-within hover:-translate-y-0.5 hover:border-ring/40 hover:shadow-md motion-reduce:hover:translate-y-0",
           className,
         )}
         {...props}

package/src/components/locale-provider/index.ts

@@ -5,4 +5,9 @@ export {
   type LocaleProviderProps,
   type Messages,
 } from "./locale-provider";
-export { DEFAULT_MESSAGES } from "./messages";
+export {
+  DEFAULT_MESSAGES,
+  type MessageValue,
+  type PluralCategory,
+  type PluralMessage,
+} from "./messages";

package/src/components/locale-provider/locale-provider.stories.tsx

@@ -2,9 +2,23 @@ import type { Meta, StoryObj } from "@storybook/react-vite";
 import { LocaleProvider, useLocale } from "./locale-provider";
 
 const meta = {
-  title: "Providers/LocaleProvider",
+  title: "Foundations/Localization",
   component: LocaleProvider,
   tags: ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "Root i18n provider — one of the two providers every app mounts once, at the root. " +
+          'Wrap it around your app inside `ThemeProvider`: `<ThemeProvider><LocaleProvider locale="en-US">…' +
+          "</LocaleProvider></ThemeProvider>`. Every component's microcopy, number formatting and " +
+          "date formatting then reads through `useLocale()`. Full resolution chain (`translate` → " +
+          "`messages` → shipped English defaults → raw key), cardinal plurals and bridging to your " +
+          "own i18n runtime (next-intl, react-intl, i18next, …): `docs/I18N.md`. See " +
+          "[Foundations / Theming](?path=/docs/foundations-theming--docs) for the other root provider.",
+      },
+    },
+  },
 } satisfies Meta<typeof LocaleProvider>;
 
 export default meta;
@@ -52,6 +66,24 @@ function LocaleDemo() {
   );
 }
 
+// ---------------------------------------------------------------------------
+// Demo component: cardinal-plural microcopy via `Intl.PluralRules`
+// ---------------------------------------------------------------------------
+
+function PluralDemo() {
+  const { t } = useLocale();
+  return (
+    <div className="space-y-1 rounded-md border border-border p-4 text-body">
+      {[0, 1, 2, 5].map((count) => (
+        <p key={count}>
+          <span className="font-medium text-muted-foreground">count={count}: </span>
+          {t("itemsSelected", { count })}
+        </p>
+      ))}
+    </div>
+  );
+}
+
 // ---------------------------------------------------------------------------
 // Stories
 // ---------------------------------------------------------------------------
@@ -81,3 +113,59 @@ export const RtlArabic: Story = {
 export const NoProvider: Story = {
   render: () => <LocaleDemo />,
 };
+
+/**
+ * The `translate` resolver bridge (#19) — stands in for an app's own i18n
+ * runtime (next-intl, react-intl, i18next, …). It takes precedence over both
+ * `messages` and the shipped English defaults; returning `undefined` for a
+ * key falls through to the normal chain. See `docs/I18N.md` for a worked
+ * next-intl example.
+ */
+export const ExternalTranslateResolver: Story = {
+  render: () => (
+    <LocaleProvider
+      locale="de-DE"
+      messages={{ close: "Schließen (via messages)" }}
+      translate={(key) => (key === "close" ? "Schließen (via translate)" : undefined)}
+    >
+      <LocaleDemo />
+    </LocaleProvider>
+  ),
+};
+
+/**
+ * Cardinal-plural microcopy (#19) — `t("itemsSelected", { count })` selects
+ * the right English form ("1 item selected" vs "N items selected") from a
+ * `PluralMessage` map as `count` changes, via `Intl.PluralRules`.
+ */
+export const PluralForms: Story = {
+  render: () => (
+    <LocaleProvider locale="en-US">
+      <PluralDemo />
+    </LocaleProvider>
+  ),
+};
+
+/**
+ * The same plural key resolved for Polish (`pl-PL`), which has FOUR cardinal
+ * categories (one/few/many/other) with different count boundaries than
+ * English's two (one/other) — the case a plural design that only handles
+ * English silently gets wrong. Count 1 → "one", 2 → "few", 5 → "many".
+ */
+export const PluralFormsPolish: Story = {
+  render: () => (
+    <LocaleProvider
+      locale="pl-PL"
+      messages={{
+        itemsSelected: {
+          one: "{count} plik zaznaczony",
+          few: "{count} pliki zaznaczone",
+          many: "{count} plików zaznaczonych",
+          other: "{count} pliku zaznaczonego",
+        },
+      }}
+    >
+      <PluralDemo />
+    </LocaleProvider>
+  ),
+};