@elabs-ai/components-ui 4.0.0

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

@@ -0,0 +1,178 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, within } from "storybook/test";
+import { LinkPreviewCard } from "./link-preview";
+
+const meta = {
+  title: "Core/LinkPreviewCard",
+  component: LinkPreviewCard,
+  tags: ["autodocs"],
+  parameters: { layout: "centered" },
+  argTypes: {
+    title: {
+      description: "Page title — the primary text, 1–2 lines.",
+      control: "text",
+      table: { category: "Content" },
+    },
+    description: {
+      description: "Short description / Open-Graph description. Omit for title+domain only.",
+      control: "text",
+      table: { category: "Content" },
+    },
+    image: {
+      description:
+        'Absolute URL of the thumbnail image (consumer-provided; decorative, alt is always "").',
+      control: "text",
+      table: { category: "Content" },
+    },
+    domain: {
+      description: 'Domain label shown with the globe icon, e.g. `"github.com"`.',
+      control: "text",
+      table: { category: "Content" },
+    },
+    href: {
+      description: "When set, the card becomes a keyboard-focusable stretched link.",
+      control: "text",
+      table: { category: "Behavior" },
+    },
+    loading: {
+      description: 'Render skeleton placeholders — sets `aria-busy="true"`.',
+      control: "boolean",
+      table: { category: "State" },
+    },
+    className: {
+      description: "Extra Tailwind classes merged via cn().",
+      control: "text",
+      table: { category: "Appearance" },
+    },
+  },
+} satisfies Meta<typeof LinkPreviewCard>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// ---------------------------------------------------------------------------
+// Loaded — full state (title + description + thumbnail + domain + href)
+// ---------------------------------------------------------------------------
+
+export const Default: Story = {
+  render: () => (
+    <LinkPreviewCard
+      className="w-96"
+      title="React documentation – Quick start"
+      description="Learn the basics of React: components, props, state, and how they fit together to build interactive UIs."
+      domain="react.dev"
+      image="https://react.dev/images/og-learn.png"
+      href="https://react.dev/learn"
+    />
+  ),
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    // Link is present and has the right href
+    const link = canvas.getByRole("link", { name: /react documentation/i });
+    await expect(link).toBeInTheDocument();
+    await expect(link).toHaveAttribute("href", "https://react.dev/learn");
+    await expect(link).toHaveAttribute("rel", "noopener noreferrer");
+    // Domain text is visible
+    await expect(canvas.getByText("react.dev")).toBeInTheDocument();
+    // Thumbnail image is decorative (aria-hidden)
+    const img = canvasElement.querySelector("img");
+    await expect(img).toHaveAttribute("aria-hidden", "true");
+    await expect(img).toHaveAttribute("alt", "");
+  },
+};
+
+// ---------------------------------------------------------------------------
+// No image — title + description + domain, thumbnail area absent
+// ---------------------------------------------------------------------------
+
+export const NoImage: Story = {
+  render: () => (
+    <LinkPreviewCard
+      className="w-96"
+      title="GitHub – elabs/elabs-components"
+      description="Source-owned, token-driven React component system for internal apps and prototypes."
+      domain="github.com"
+      href="https://github.com/elabs/elabs-components"
+    />
+  ),
+  play: async ({ canvasElement }) => {
+    // No <img> element rendered when image prop is absent
+    const img = canvasElement.querySelector("img");
+    await expect(img).toBeNull();
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Title + domain only — no description
+// ---------------------------------------------------------------------------
+
+export const TitleAndDomainOnly: Story = {
+  render: () => (
+    <LinkPreviewCard
+      className="w-96"
+      title="Tailwind CSS – Utility-first CSS framework"
+      domain="tailwindcss.com"
+      href="https://tailwindcss.com"
+    />
+  ),
+};
+
+// ---------------------------------------------------------------------------
+// Loading — skeleton state
+// ---------------------------------------------------------------------------
+
+export const Loading: Story = {
+  render: () => <LinkPreviewCard className="w-96" loading />,
+  play: async ({ canvasElement }) => {
+    const card = canvasElement.querySelector("[aria-busy]");
+    await expect(card).toHaveAttribute("aria-busy", "true");
+    // No real content rendered while loading
+    const link = canvasElement.querySelector("a");
+    await expect(link).toBeNull();
+  },
+};
+
+// ---------------------------------------------------------------------------
+// No href — static / non-interactive card
+// ---------------------------------------------------------------------------
+
+export const Static: Story = {
+  render: () => (
+    <LinkPreviewCard
+      className="w-96"
+      title="MDN Web Docs – HTML: HyperText Markup Language"
+      description="HTML is the standard markup language for Web pages. With HTML you can create your own Website."
+      domain="developer.mozilla.org"
+      image="https://developer.mozilla.org/mdn-social-share.png"
+    />
+  ),
+  play: async ({ canvasElement }) => {
+    // Static card: no <a> link present
+    const link = canvasElement.querySelector("a");
+    await expect(link).toBeNull();
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Empty / minimal — no props except className: degrades gracefully
+// ---------------------------------------------------------------------------
+
+export const Empty: Story = {
+  render: () => <LinkPreviewCard className="w-96" />,
+};
+
+// ---------------------------------------------------------------------------
+// Long content — line-clamp kicks in, no overflow
+// ---------------------------------------------------------------------------
+
+export const LongContent: Story = {
+  render: () => (
+    <LinkPreviewCard
+      className="w-96"
+      title="This is a very long page title that will wrap across multiple lines and should be clamped after two lines to prevent the card from growing too tall in a feed or sidebar context"
+      description="And here is an equally long description — the kind you might get from an overly verbose Open Graph meta tag that tries to include every detail of the page. It should be clamped at two lines."
+      domain="example-with-a-very-long-subdomain.internal.enterprise.example.com"
+      href="https://example.com"
+    />
+  ),
+};

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

@@ -0,0 +1,123 @@
+import { describe, expect, it } from "vitest";
+import { render, screen } from "@testing-library/react";
+import { LinkPreview, LinkPreviewCard } from "./link-preview";
+
+describe("LinkPreviewCard", () => {
+  // -------------------------------------------------------------------------
+  // Loaded state
+  // -------------------------------------------------------------------------
+
+  it("renders title, description, and domain", () => {
+    render(
+      <LinkPreviewCard
+        title="React – Quick start"
+        description="Learn the basics."
+        domain="react.dev"
+      />,
+    );
+    expect(screen.getByText("React – Quick start")).toBeInTheDocument();
+    expect(screen.getByText("Learn the basics.")).toBeInTheDocument();
+    expect(screen.getByText("react.dev")).toBeInTheDocument();
+  });
+
+  it("renders a real <a> link when href is provided", () => {
+    render(
+      <LinkPreviewCard title="React docs" href="https://react.dev/learn" domain="react.dev" />,
+    );
+    const link = screen.getByRole("link", { name: /react docs/i });
+    expect(link).toBeInTheDocument();
+    expect(link).toHaveAttribute("href", "https://react.dev/learn");
+    expect(link).toHaveAttribute("rel", "noopener noreferrer");
+    expect(link).toHaveAttribute("target", "_blank");
+  });
+
+  it("renders no <a> element when href is absent", () => {
+    render(<LinkPreviewCard title="Static card" domain="example.com" />);
+    expect(screen.queryByRole("link")).toBeNull();
+  });
+
+  // -------------------------------------------------------------------------
+  // Loading state
+  // -------------------------------------------------------------------------
+
+  it("sets aria-busy when loading", () => {
+    render(<LinkPreviewCard loading data-testid="card" />);
+    const card = screen.getByTestId("card");
+    expect(card).toHaveAttribute("aria-busy", "true");
+  });
+
+  it("does not render real content when loading", () => {
+    render(
+      <LinkPreviewCard
+        loading
+        title="Should not appear"
+        description="Hidden"
+        domain="example.com"
+      />,
+    );
+    expect(screen.queryByText("Should not appear")).toBeNull();
+    expect(screen.queryByRole("link")).toBeNull();
+  });
+
+  it("does not set aria-busy when not loading", () => {
+    render(<LinkPreviewCard title="Loaded" data-testid="card" />);
+    const card = screen.getByTestId("card");
+    // aria-busy is undefined (not present) when not loading
+    expect(card).not.toHaveAttribute("aria-busy");
+  });
+
+  // -------------------------------------------------------------------------
+  // No image
+  // -------------------------------------------------------------------------
+
+  it("renders no <img> when image prop is absent", () => {
+    const { container } = render(<LinkPreviewCard title="No image" />);
+    expect(container.querySelector("img")).toBeNull();
+  });
+
+  it("renders a decorative <img> with alt='' when image is provided", () => {
+    const { container } = render(
+      <LinkPreviewCard title="Has image" image="https://example.com/og.png" />,
+    );
+    const img = container.querySelector("img");
+    expect(img).not.toBeNull();
+    expect(img).toHaveAttribute("alt", "");
+    expect(img).toHaveAttribute("aria-hidden", "true");
+    expect(img).toHaveAttribute("src", "https://example.com/og.png");
+  });
+
+  // -------------------------------------------------------------------------
+  // Composability
+  // -------------------------------------------------------------------------
+
+  it("forwards className and extra props to the root element", () => {
+    render(
+      <LinkPreviewCard
+        title="Composable"
+        className="my-custom-class"
+        data-testid="card"
+        aria-label="Link preview"
+      />,
+    );
+    const card = screen.getByTestId("card");
+    expect(card).toHaveClass("my-custom-class");
+    expect(card).toHaveAttribute("aria-label", "Link preview");
+  });
+
+  it("renders children inside the card", () => {
+    render(
+      <LinkPreviewCard title="With children">
+        <span data-testid="child">Extra content</span>
+      </LinkPreviewCard>,
+    );
+    expect(screen.getByTestId("child")).toBeInTheDocument();
+  });
+
+  // -------------------------------------------------------------------------
+  // LinkPreview alias
+  // -------------------------------------------------------------------------
+
+  it("LinkPreview is the same component as LinkPreviewCard", () => {
+    expect(LinkPreview).toBe(LinkPreviewCard);
+  });
+});

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

@@ -0,0 +1,194 @@
+"use client";
+
+import { forwardRef, type HTMLAttributes } from "react";
+import { GlobeIcon } from "lucide-react";
+import { cn } from "../../lib/cn";
+import { Skeleton } from "../skeleton/skeleton";
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+export interface LinkPreviewCardProps extends HTMLAttributes<HTMLDivElement> {
+  /** Page title — the primary text, 1–2 lines. */
+  title?: string;
+  /** Short description / Open-Graph description. Omit for title+domain only. */
+  description?: string;
+  /**
+   * Absolute URL of the thumbnail image (consumer-provided; the library never
+   * fetches). Decorative — `alt` is always `""`. Omit to hide the thumbnail
+   * area cleanly (no broken-image placeholder).
+   */
+  image?: string;
+  /**
+   * Domain label shown with the globe icon, e.g. `"github.com"`. Wrapped in
+   * `translate="no"` so browsers never auto-translate identifiers.
+   */
+  domain?: string;
+  /**
+   * When set, the entire card becomes a keyboard-focusable link (stretched-link
+   * pattern). The visible focus ring is placed on the card via `focus-within`.
+   * Prefer a full absolute URL so the `<a>` is meaningful.
+   */
+  href?: string;
+  /**
+   * Render skeleton placeholders in lieu of real content. Sets `aria-busy="true"`
+   * on the card root so assistive technology knows the content is pending.
+   */
+  loading?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/** Thumbnail — hidden when `image` is absent (no broken-icon placeholder). */
+function Thumbnail({ image }: { image?: string }) {
+  if (!image) return null;
+  return (
+    <div className="relative h-full w-28 shrink-0 overflow-hidden rounded-e-lg">
+      {/* explicit width/height prevent CLS; object-cover fills the container */}
+      <img
+        src={image}
+        alt="" // decorative; title carries meaning
+        aria-hidden="true"
+        width={112}
+        height={112}
+        loading="lazy"
+        className="h-full w-full object-cover"
+      />
+    </div>
+  );
+}
+
+/** Skeleton layout matching the card shape. */
+function SkeletonLayout() {
+  return (
+    <div className="flex min-h-[5rem] gap-3 p-3">
+      <div className="flex min-w-0 flex-1 flex-col gap-2 py-0.5">
+        {/* domain row */}
+        <Skeleton className="h-3 w-24" />
+        {/* title — two lines */}
+        <Skeleton className="h-4 w-full" />
+        <Skeleton className="h-4 w-3/4" />
+        {/* description */}
+        <Skeleton className="mt-1 h-3 w-full" />
+        <Skeleton className="h-3 w-5/6" />
+      </div>
+      {/* thumbnail placeholder */}
+      <Skeleton className="h-20 w-28 shrink-0 rounded-md" />
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// LinkPreviewCard
+// ---------------------------------------------------------------------------
+
+/**
+ * A rich, presentational link-preview card (unfurled URL / bookmark block).
+ * Renders favicon/domain, title, description, and an optional thumbnail from
+ * **consumer-provided** metadata — the library never fetches.
+ *
+ * States: `loading` (skeleton), loaded (full), no-image, no-description
+ * (title + domain only), and empty/error (degrades to a plain placeholder).
+ *
+ * Pass `href` to make the whole card a keyboard-focusable stretched link.
+ * Use `loading` for the skeleton state; set `aria-busy` is applied automatically.
+ */
+export const LinkPreviewCard = forwardRef<HTMLDivElement, LinkPreviewCardProps>(
+  function LinkPreviewCard(
+    { className, title, description, image, domain, href, loading = false, children, ...props },
+    ref,
+  ) {
+    return (
+      <div
+        ref={ref}
+        aria-busy={loading || undefined}
+        className={cn(
+          // Base card chrome — rounded border, card surface, subtle shadow
+          "relative overflow-hidden rounded-lg border bg-card text-card-foreground shadow-sm",
+          // Stretched-link focus ring: when `href` is present the inner <a>
+          // covers the whole card; the ring is painted on the card container via
+          // focus-within so the outer border gets the visible ring, not the
+          // hidden absolutely-positioned link.
+          // 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",
+          className,
+        )}
+        {...props}
+      >
+        {loading ? (
+          <SkeletonLayout />
+        ) : (
+          <div className="flex min-h-[5rem] gap-0">
+            {/* Main content */}
+            <div className="flex min-w-0 flex-1 flex-col justify-center gap-1.5 p-3">
+              {/* Domain row */}
+              {domain && (
+                <p className="flex items-center gap-1.5 text-meta text-muted-foreground">
+                  <GlobeIcon aria-hidden="true" className="size-3 shrink-0" />
+                  {/* translate="no" so browsers never auto-translate domain identifiers */}
+                  <span className="truncate" translate="no">
+                    {domain}
+                  </span>
+                </p>
+              )}
+
+              {/* Title */}
+              {title && (
+                <p className="line-clamp-2 min-w-0 text-body font-medium leading-snug">
+                  {href ? (
+                    /*
+                     * Stretched-link pattern: `<a>` is absolutely positioned to
+                     * cover the entire card (after:absolute after:inset-0). The
+                     * visible focus ring lives on the card container via
+                     * focus-within (above). `focus-visible:outline-none` removes
+                     * the browser's own ring on the link so it doesn't double up.
+                     */
+                    <a
+                      href={href}
+                      target="_blank"
+                      rel="noopener noreferrer"
+                      className="after:absolute after:inset-0 focus-visible:outline-none"
+                    >
+                      {title}
+                    </a>
+                  ) : (
+                    title
+                  )}
+                </p>
+              )}
+
+              {/* Description */}
+              {description && (
+                <p className="line-clamp-2 min-w-0 text-caption text-muted-foreground">
+                  {description}
+                </p>
+              )}
+
+              {children}
+            </div>
+
+            {/* Thumbnail — conditionally rendered */}
+            <Thumbnail image={image} />
+          </div>
+        )}
+      </div>
+    );
+  },
+);
+
+// ---------------------------------------------------------------------------
+// LinkPreview alias
+// ---------------------------------------------------------------------------
+
+/**
+ * Convenience alias for `LinkPreviewCard`. Identical component — use whichever
+ * name reads more naturally at the call site.
+ *
+ * `LinkPreviewCard` is the canonical export; `LinkPreview` is the alias.
+ */
+export const LinkPreview = LinkPreviewCard;

package/src/components/list-editor/index.ts

@@ -0,0 +1 @@
+export { ListEditor, type ListEditorProps } from "./list-editor";

package/src/components/list-editor/list-editor.stories.tsx

@@ -0,0 +1,119 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect } from "storybook/test";
+import { useState } from "react";
+import { ListEditor } from "./list-editor";
+
+const meta = {
+  title: "Forms/ListEditor",
+  component: ListEditor,
+  tags: ["autodocs"],
+  args: {
+    placeholder: "--flag=value…",
+  },
+  argTypes: {
+    value: {
+      description: "Controlled list of strings.",
+      control: false,
+      table: { category: "State" },
+    },
+    defaultValue: {
+      description: "Uncontrolled initial list of strings.",
+      control: false,
+      table: { category: "State" },
+    },
+    reorderable: {
+      description: "Whether rows can be reordered via move-up/move-down buttons.",
+      control: "boolean",
+      table: { category: "Behavior" },
+    },
+    max: {
+      description: "Maximum number of rows allowed.",
+      control: "number",
+      table: { category: "Behavior" },
+    },
+    placeholder: {
+      description: "Placeholder shown in each row's text field.",
+      control: "text",
+      table: { category: "Content" },
+    },
+    disabled: {
+      description: "Disables the editor.",
+      control: "boolean",
+      table: { category: "State" },
+    },
+    addLabel: {
+      description: 'Label for the "add item" control.',
+      control: "text",
+      table: { category: "Content" },
+    },
+    onValueChange: {
+      description: "Called when the list changes.",
+      control: false,
+      table: { category: "Behavior" },
+    },
+    className: {
+      description: "Additional CSS classes applied to the root element.",
+      control: "text",
+      table: { category: "Appearance" },
+    },
+  },
+} satisfies Meta<typeof ListEditor>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: { defaultValue: ["--verbose", "--output=json"] },
+};
+
+export const Controlled: Story = {
+  render: () => {
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    const [items, setItems] = useState(["one", "two"]);
+    return (
+      <div className="flex flex-col gap-2 max-w-sm">
+        <ListEditor value={items} onValueChange={setItems} placeholder="Item…" />
+        <p className="text-body text-muted-foreground">Items: {items.join(", ") || "none"}</p>
+      </div>
+    );
+  },
+};
+
+export const NonReorderable: Story = {
+  args: { defaultValue: ["first", "second"], reorderable: false },
+};
+
+/** Adds a row, types into it, removes a row, and moves a row up — all via real buttons. */
+export const AddEditRemoveMove: Story = {
+  args: { defaultValue: ["alpha", "beta"] },
+  play: async ({ canvas, userEvent }) => {
+    await userEvent.click(canvas.getByRole("button", { name: /add item/i }));
+    const rowInputs = canvas.getAllByRole("textbox");
+    await expect(rowInputs).toHaveLength(3);
+    await userEvent.type(rowInputs[2]!, "gamma");
+    await expect(rowInputs[2]).toHaveValue("gamma");
+
+    // Move the last row up one position via the keyboard-operable button.
+    const moveUpButtons = canvas.getAllByRole("button", { name: /move item 3 up/i });
+    await userEvent.click(moveUpButtons[0]!);
+    const afterMove = canvas.getAllByRole("textbox");
+    await expect(afterMove[1]).toHaveValue("gamma");
+
+    await userEvent.click(canvas.getAllByRole("button", { name: /remove item 1/i })[0]!);
+    await expect(canvas.getAllByRole("textbox")).toHaveLength(2);
+  },
+};
+
+export const WithMax: Story = {
+  args: { defaultValue: ["one", "two"], max: 2 },
+};
+
+export const Disabled: Story = {
+  args: { defaultValue: ["locked"], disabled: true },
+};
+
+export const Empty: Story = {
+  args: { defaultValue: [] },
+  play: async ({ canvas }) => {
+    await expect(canvas.getByText("No items yet.")).toBeInTheDocument();
+  },
+};