@dillingerstaffing/strand-ui 0.1.0 → 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,64 @@
+/*! Strand UI v0.1.0 | MIT License | dillingerstaffing.com */
+export { Button } from "./components/Button/index.js";
+export type { ButtonProps } from "./components/Button/index.js";
+export { Input } from "./components/Input/index.js";
+export type { InputProps } from "./components/Input/index.js";
+export { Textarea } from "./components/Textarea/index.js";
+export type { TextareaProps } from "./components/Textarea/index.js";
+export { Select } from "./components/Select/index.js";
+export type { SelectProps, SelectOption } from "./components/Select/index.js";
+export { Checkbox } from "./components/Checkbox/index.js";
+export type { CheckboxProps } from "./components/Checkbox/index.js";
+export { Radio } from "./components/Radio/index.js";
+export type { RadioProps } from "./components/Radio/index.js";
+export { Switch } from "./components/Switch/index.js";
+export type { SwitchProps } from "./components/Switch/index.js";
+export { Slider } from "./components/Slider/index.js";
+export type { SliderProps } from "./components/Slider/index.js";
+export { FormField } from "./components/FormField/index.js";
+export type { FormFieldProps } from "./components/FormField/index.js";
+export { Card } from "./components/Card/index.js";
+export type { CardProps } from "./components/Card/index.js";
+export { Badge } from "./components/Badge/index.js";
+export type { BadgeProps } from "./components/Badge/index.js";
+export { Avatar } from "./components/Avatar/index.js";
+export type { AvatarProps } from "./components/Avatar/index.js";
+export { Tag } from "./components/Tag/index.js";
+export type { TagProps } from "./components/Tag/index.js";
+export { Table } from "./components/Table/index.js";
+export type { TableProps, TableColumn } from "./components/Table/index.js";
+export { DataReadout } from "./components/DataReadout/index.js";
+export type { DataReadoutProps } from "./components/DataReadout/index.js";
+export { Stack } from "./components/Stack/index.js";
+export type { StackProps } from "./components/Stack/index.js";
+export { Grid } from "./components/Grid/index.js";
+export type { GridProps } from "./components/Grid/index.js";
+export { Container } from "./components/Container/index.js";
+export type { ContainerProps } from "./components/Container/index.js";
+export { Divider } from "./components/Divider/index.js";
+export type { DividerProps } from "./components/Divider/index.js";
+export { Section } from "./components/Section/index.js";
+export type { SectionProps } from "./components/Section/index.js";
+export { Link } from "./components/Link/index.js";
+export type { LinkProps } from "./components/Link/index.js";
+export { Tabs } from "./components/Tabs/index.js";
+export type { TabsProps, TabItem } from "./components/Tabs/index.js";
+export { Breadcrumb } from "./components/Breadcrumb/index.js";
+export type { BreadcrumbProps, BreadcrumbItem } from "./components/Breadcrumb/index.js";
+export { Nav } from "./components/Nav/index.js";
+export type { NavProps } from "./components/Nav/index.js";
+export { Toast, ToastProvider, useToast } from "./components/Toast/index.js";
+export type { ToastProps } from "./components/Toast/index.js";
+export { Alert } from "./components/Alert/index.js";
+export type { AlertProps } from "./components/Alert/index.js";
+export { Dialog } from "./components/Dialog/index.js";
+export type { DialogProps } from "./components/Dialog/index.js";
+export { Tooltip } from "./components/Tooltip/index.js";
+export type { TooltipProps } from "./components/Tooltip/index.js";
+export { Progress } from "./components/Progress/index.js";
+export type { ProgressProps } from "./components/Progress/index.js";
+export { Spinner } from "./components/Spinner/index.js";
+export type { SpinnerProps } from "./components/Spinner/index.js";
+export { Skeleton } from "./components/Skeleton/index.js";
+export type { SkeletonProps } from "./components/Skeleton/index.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/test-setup.d.ts

@@ -0,0 +1,2 @@
+import "@testing-library/jest-dom/vitest";
+//# sourceMappingURL=test-setup.d.ts.map

package/dist/test-setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-setup.d.ts","sourceRoot":"","sources":["../src/test-setup.ts"],"names":[],"mappings":"AAAA,OAAO,kCAAkC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dillingerstaffing/strand-ui",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Strand UI - Preact/React component library built on the Strand Design Language",
   "author": "Dillinger Staffing <engineering@dillingerstaffing.com> (https://dillingerstaffing.com)",
   "license": "MIT",
@@ -22,20 +22,15 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
-    "./css/*": "./dist/css/*"
+    "./css/strand-ui.css": "./dist/css/strand-ui.css"
   },
   "files": [
-    "dist/"
+    "dist/",
+    "src/"
   ],
   "sideEffects": [
     "dist/css/*.css"
   ],
-  "scripts": {
-    "build": "vite build",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage"
-  },
   "peerDependencies": {
     "preact": "^10.0.0"
   },
@@ -45,7 +40,7 @@
     }
   },
   "dependencies": {
-    "@dillingerstaffing/strand": "workspace:*"
+    "@dillingerstaffing/strand": "0.1.1"
   },
   "devDependencies": {
     "@testing-library/preact": "^3.2.0",
@@ -54,5 +49,11 @@
     "preact": "^10.25.0",
     "vite": "^6.0.0",
     "vitest": "^3.0.0"
+  },
+  "scripts": {
+    "build": "vite build && tsc --emitDeclarationOnly",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
   }
-}
+}

package/src/__tests__/build-output.test.ts

@@ -0,0 +1,77 @@
+import { describe, expect, it } from "vitest";
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+const distDir = resolve(__dirname, "../../dist");
+
+describe("Build output", () => {
+  it("produces index.js bundle", () => {
+    expect(existsSync(resolve(distDir, "index.js"))).toBe(true);
+  });
+
+  it("produces index.d.ts declarations", () => {
+    expect(existsSync(resolve(distDir, "index.d.ts"))).toBe(true);
+  });
+
+  it("declarations export all component types", () => {
+    const dts = readFileSync(resolve(distDir, "index.d.ts"), "utf-8");
+    const expectedExports = [
+      "Button", "Input", "Textarea", "Select", "Checkbox", "Radio",
+      "Switch", "Slider", "FormField", "Card", "Badge", "Avatar",
+      "Tag", "Table", "DataReadout", "Stack", "Grid", "Container",
+      "Divider", "Section", "Link", "Tabs", "Breadcrumb", "Nav",
+      "Toast", "Alert", "Dialog", "Tooltip", "Progress", "Spinner", "Skeleton",
+    ];
+    for (const name of expectedExports) {
+      expect(dts, `Missing export: ${name}`).toContain(name);
+    }
+  });
+
+  it("produces combined CSS file", () => {
+    expect(existsSync(resolve(distDir, "css/strand-ui.css"))).toBe(true);
+  });
+
+  it("CSS file contains styles for all components", () => {
+    const css = readFileSync(resolve(distDir, "css/strand-ui.css"), "utf-8");
+    const expectedClasses = [
+      ".strand-btn", ".strand-input", ".strand-select",
+      ".strand-checkbox", ".strand-radio", ".strand-switch",
+      ".strand-slider", ".strand-card", ".strand-badge",
+      ".strand-avatar", ".strand-tag", ".strand-table",
+      ".strand-data-readout", ".strand-stack", ".strand-grid",
+      ".strand-container", ".strand-divider", ".strand-section",
+      ".strand-link", ".strand-tabs", ".strand-breadcrumb",
+      ".strand-nav", ".strand-toast", ".strand-alert",
+      ".strand-dialog", ".strand-tooltip", ".strand-progress",
+      ".strand-spinner", ".strand-skeleton",
+    ];
+    for (const cls of expectedClasses) {
+      expect(css, `Missing CSS class: ${cls}`).toContain(cls);
+    }
+  });
+
+  it("CSS file uses only strand tokens (no hardcoded colors)", () => {
+    const css = readFileSync(resolve(distDir, "css/strand-ui.css"), "utf-8");
+    // Remove comments and check for hardcoded hex colors that aren't in rgba()
+    const withoutComments = css.replace(/\/\*[\s\S]*?\*\//g, "");
+    const hexMatches = withoutComments.match(/#[0-9a-fA-F]{6}\b/g) || [];
+    // Filter out known exceptions (danger hover/active states that extend the palette)
+    const knownExceptions = ["#DC2626", "#B91C1C", "#0D7377", "#92400E", "#991B1B"];
+    const unexpected = hexMatches.filter(
+      (h) => !knownExceptions.includes(h.toUpperCase())
+    );
+    expect(unexpected, `Hardcoded hex colors found: ${unexpected.join(", ")}`).toEqual([]);
+  });
+
+  it("JS bundle is under 50KB gzipped budget", () => {
+    const js = readFileSync(resolve(distDir, "index.js"), "utf-8");
+    // Rough check: uncompressed should be well under 200KB (gzip ~4:1 ratio)
+    expect(js.length).toBeLessThan(200_000);
+  });
+
+  it("src/ directory exists for CLI copy-paste", () => {
+    expect(existsSync(resolve(__dirname, "../components/Button/Button.tsx"))).toBe(true);
+    expect(existsSync(resolve(__dirname, "../components/Button/Button.css"))).toBe(true);
+    expect(existsSync(resolve(__dirname, "../components/Dialog/Dialog.tsx"))).toBe(true);
+  });
+});

package/src/components/Alert/Alert.css

@@ -0,0 +1,67 @@
+/*! Strand UI | MIT License | dillingerstaffing.com */
+
+/* ── Base ── */
+.strand-alert {
+  position: relative;
+  display: flex;
+  align-items: flex-start;
+  justify-content: space-between;
+  width: 100%;
+  padding: var(--strand-space-4);
+  border-radius: var(--strand-radius-md);
+  border-left: 4px solid transparent;
+  font-family: var(--strand-font-sans);
+  font-size: var(--strand-text-sm);
+}
+
+/* ── Status variants ── */
+.strand-alert--info {
+  background: var(--strand-blue-glow);
+  border-left-color: var(--strand-blue-primary);
+}
+
+.strand-alert--success {
+  background: rgba(34, 197, 94, 0.08);
+  border-left-color: var(--strand-green-positive);
+}
+
+.strand-alert--warning {
+  background: rgba(245, 158, 11, 0.08);
+  border-left-color: var(--strand-amber-caution);
+}
+
+.strand-alert--error {
+  background: rgba(239, 68, 68, 0.08);
+  border-left-color: var(--strand-red-alert);
+}
+
+/* ── Content ── */
+.strand-alert__content {
+  flex: 1;
+  min-width: 0;
+}
+
+/* ── Dismiss button ── */
+.strand-alert__dismiss {
+  flex-shrink: 0;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 24px;
+  height: 24px;
+  margin-left: var(--strand-space-4);
+  padding: 0;
+  border: none;
+  border-radius: var(--strand-radius-md);
+  background: transparent;
+  color: var(--strand-gray-500);
+  font-size: var(--strand-text-base);
+  cursor: pointer;
+  transition: background var(--strand-duration-fast) ease,
+    color var(--strand-duration-fast) ease;
+}
+
+.strand-alert__dismiss:hover {
+  background: var(--strand-gray-100);
+  color: var(--strand-gray-600);
+}

package/src/components/Alert/Alert.test.tsx

@@ -0,0 +1,92 @@
+import { describe, expect, it, vi } from "vitest";
+import { render, fireEvent } from "@testing-library/preact";
+import { Alert } from "./Alert.js";
+
+describe("Alert", () => {
+  // ── Rendering ──
+
+  it("renders children text", () => {
+    const { getByRole } = render(<Alert>Something happened</Alert>);
+    expect(getByRole("status")).toHaveTextContent("Something happened");
+  });
+
+  // ── Status classes ──
+
+  it("applies info status class by default", () => {
+    const { getByRole } = render(<Alert>Info</Alert>);
+    expect(getByRole("status").className).toContain("strand-alert--info");
+  });
+
+  it("applies success status class", () => {
+    const { getByRole } = render(<Alert status="success">OK</Alert>);
+    expect(getByRole("status").className).toContain("strand-alert--success");
+  });
+
+  it("applies warning status class", () => {
+    const { getByRole } = render(<Alert status="warning">Warn</Alert>);
+    expect(getByRole("alert").className).toContain("strand-alert--warning");
+  });
+
+  it("applies error status class", () => {
+    const { getByRole } = render(<Alert status="error">Fail</Alert>);
+    expect(getByRole("alert").className).toContain("strand-alert--error");
+  });
+
+  // ── ARIA roles ──
+
+  it("uses role alert for error status", () => {
+    const { getByRole } = render(<Alert status="error">Err</Alert>);
+    expect(getByRole("alert")).toBeTruthy();
+  });
+
+  it("uses role alert for warning status", () => {
+    const { getByRole } = render(<Alert status="warning">Warn</Alert>);
+    expect(getByRole("alert")).toBeTruthy();
+  });
+
+  it("uses role status for info status", () => {
+    const { getByRole } = render(<Alert status="info">Info</Alert>);
+    expect(getByRole("status")).toBeTruthy();
+  });
+
+  it("uses role status for success status", () => {
+    const { getByRole } = render(<Alert status="success">OK</Alert>);
+    expect(getByRole("status")).toBeTruthy();
+  });
+
+  // ── Dismissible ──
+
+  it("shows dismiss button when dismissible", () => {
+    const { getByLabelText } = render(
+      <Alert dismissible>Dismissible</Alert>,
+    );
+    expect(getByLabelText("Dismiss")).toBeTruthy();
+  });
+
+  it("calls onDismiss when dismiss button is clicked", () => {
+    const onDismiss = vi.fn();
+    const { getByLabelText } = render(
+      <Alert dismissible onDismiss={onDismiss}>
+        Dismiss me
+      </Alert>,
+    );
+    fireEvent.click(getByLabelText("Dismiss"));
+    expect(onDismiss).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not show dismiss button when not dismissible", () => {
+    const { queryByLabelText } = render(<Alert>Not dismissible</Alert>);
+    expect(queryByLabelText("Dismiss")).toBeNull();
+  });
+
+  // ── Custom className ──
+
+  it("merges custom className", () => {
+    const { getByRole } = render(
+      <Alert className="custom">Content</Alert>,
+    );
+    const el = getByRole("status");
+    expect(el.className).toContain("strand-alert");
+    expect(el.className).toContain("custom");
+  });
+});

package/src/components/Alert/Alert.tsx

@@ -0,0 +1,59 @@
+/*! Strand UI | MIT License | dillingerstaffing.com */
+
+import type { ComponentChildren, JSX } from "preact";
+import { forwardRef } from "preact/compat";
+
+export interface AlertProps
+  extends Omit<JSX.HTMLAttributes<HTMLDivElement>, "status"> {
+  /** Visual status of the alert */
+  status?: "info" | "success" | "warning" | "error";
+  /** Show dismiss button */
+  dismissible?: boolean;
+  /** Called when dismiss button is clicked */
+  onDismiss?: () => void;
+  /** Alert content */
+  children?: ComponentChildren;
+}
+
+export const Alert = forwardRef<HTMLDivElement, AlertProps>(
+  (
+    {
+      status = "info",
+      dismissible = false,
+      onDismiss,
+      className = "",
+      children,
+      ...rest
+    },
+    ref,
+  ) => {
+    const role =
+      status === "error" || status === "warning" ? "alert" : "status";
+
+    const classes = [
+      "strand-alert",
+      `strand-alert--${status}`,
+      className,
+    ]
+      .filter(Boolean)
+      .join(" ");
+
+    return (
+      <div ref={ref} className={classes} role={role} {...rest}>
+        <div className="strand-alert__content">{children}</div>
+        {dismissible && (
+          <button
+            type="button"
+            className="strand-alert__dismiss"
+            aria-label="Dismiss"
+            onClick={onDismiss}
+          >
+            &#215;
+          </button>
+        )}
+      </div>
+    );
+  },
+);
+
+Alert.displayName = "Alert";

package/src/components/Alert/index.ts

@@ -0,0 +1,2 @@
+export { Alert } from "./Alert.js";
+export type { AlertProps } from "./Alert.js";

package/src/components/Avatar/Avatar.css

@@ -0,0 +1,55 @@
+/*! Strand UI | MIT License | dillingerstaffing.com */
+
+/* ── Base ── */
+.strand-avatar {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  border-radius: var(--strand-radius-full);
+  background: var(--strand-surface-recessed);
+  overflow: hidden;
+  flex-shrink: 0;
+  font-family: var(--strand-font-sans);
+  font-weight: var(--strand-weight-medium);
+  color: var(--strand-gray-600);
+  user-select: none;
+}
+
+/* ── Image ── */
+.strand-avatar__img {
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+  border-radius: var(--strand-radius-full);
+}
+
+/* ── Initials ── */
+.strand-avatar__initials {
+  text-transform: uppercase;
+  line-height: 1;
+}
+
+/* ── Sizes ── */
+.strand-avatar--sm {
+  width: 32px;
+  height: 32px;
+  font-size: var(--strand-text-xs);
+}
+
+.strand-avatar--md {
+  width: 40px;
+  height: 40px;
+  font-size: var(--strand-text-sm);
+}
+
+.strand-avatar--lg {
+  width: 48px;
+  height: 48px;
+  font-size: var(--strand-text-base);
+}
+
+.strand-avatar--xl {
+  width: 64px;
+  height: 64px;
+  font-size: var(--strand-text-lg);
+}

package/src/components/Avatar/Avatar.test.tsx

@@ -0,0 +1,123 @@
+import { describe, expect, it } from "vitest";
+import { render, fireEvent } from "@testing-library/preact";
+import { Avatar } from "./Avatar.js";
+
+describe("Avatar", () => {
+  // ── Image mode ──
+
+  it("renders image when src is provided", () => {
+    const { container } = render(
+      <Avatar src="https://example.com/photo.jpg" alt="Jane Doe" />,
+    );
+    const img = container.querySelector("img");
+    expect(img).toBeTruthy();
+    expect(img?.getAttribute("src")).toBe("https://example.com/photo.jpg");
+  });
+
+  it("sets alt text on image", () => {
+    const { container } = render(
+      <Avatar src="https://example.com/photo.jpg" alt="Jane Doe" />,
+    );
+    const img = container.querySelector("img");
+    expect(img?.getAttribute("alt")).toBe("Jane Doe");
+  });
+
+  // ── Initials mode ──
+
+  it("shows initials when no src is provided", () => {
+    const { container } = render(<Avatar initials="jd" />);
+    const initialsEl = container.querySelector(".strand-avatar__initials");
+    expect(initialsEl).toBeTruthy();
+    expect(initialsEl?.textContent).toBe("JD");
+  });
+
+  it("initials are uppercase", () => {
+    const { container } = render(<Avatar initials="ab" />);
+    const initialsEl = container.querySelector(".strand-avatar__initials");
+    expect(initialsEl?.textContent).toBe("AB");
+  });
+
+  it("truncates initials to 2 characters", () => {
+    const { container } = render(<Avatar initials="abc" />);
+    const initialsEl = container.querySelector(".strand-avatar__initials");
+    expect(initialsEl?.textContent).toBe("AB");
+  });
+
+  // ── Fallback ──
+
+  it("falls back to initials on image error", () => {
+    const { container } = render(
+      <Avatar src="https://example.com/broken.jpg" initials="jd" alt="Jane" />,
+    );
+    const img = container.querySelector("img");
+    expect(img).toBeTruthy();
+
+    fireEvent.error(img!);
+
+    const initialsEl = container.querySelector(".strand-avatar__initials");
+    expect(initialsEl).toBeTruthy();
+    expect(initialsEl?.textContent).toBe("JD");
+    expect(container.querySelector("img")).toBeNull();
+  });
+
+  // ── Sizes ──
+
+  it("applies md size class by default", () => {
+    const { container } = render(<Avatar initials="A" />);
+    expect(container.firstElementChild?.className).toContain(
+      "strand-avatar--md",
+    );
+  });
+
+  it("applies sm size class", () => {
+    const { container } = render(<Avatar initials="A" size="sm" />);
+    expect(container.firstElementChild?.className).toContain(
+      "strand-avatar--sm",
+    );
+  });
+
+  it("applies lg size class", () => {
+    const { container } = render(<Avatar initials="A" size="lg" />);
+    expect(container.firstElementChild?.className).toContain(
+      "strand-avatar--lg",
+    );
+  });
+
+  it("applies xl size class", () => {
+    const { container } = render(<Avatar initials="A" size="xl" />);
+    expect(container.firstElementChild?.className).toContain(
+      "strand-avatar--xl",
+    );
+  });
+
+  // ── Shape ──
+
+  it("has circular shape class", () => {
+    const { container } = render(<Avatar initials="A" />);
+    expect(container.firstElementChild?.className).toContain("strand-avatar");
+  });
+
+  // ── Custom className ──
+
+  it("merges custom className", () => {
+    const { container } = render(<Avatar initials="A" className="custom" />);
+    const el = container.firstElementChild;
+    expect(el?.className).toContain("strand-avatar");
+    expect(el?.className).toContain("custom");
+  });
+
+  // ── Accessibility ──
+
+  it("has role img and aria-label", () => {
+    const { container } = render(<Avatar initials="JD" alt="Jane Doe" />);
+    const el = container.firstElementChild;
+    expect(el?.getAttribute("role")).toBe("img");
+    expect(el?.getAttribute("aria-label")).toBe("Jane Doe");
+  });
+
+  it("uses initials for aria-label when no alt", () => {
+    const { container } = render(<Avatar initials="jd" />);
+    const el = container.firstElementChild;
+    expect(el?.getAttribute("aria-label")).toBe("JD");
+  });
+});

package/src/components/Avatar/Avatar.tsx

@@ -0,0 +1,67 @@
+/*! Strand UI | MIT License | dillingerstaffing.com */
+
+import type { JSX } from "preact";
+import { forwardRef } from "preact/compat";
+import { useState, useCallback } from "preact/hooks";
+
+export interface AvatarProps
+  extends Omit<JSX.HTMLAttributes<HTMLDivElement>, "size"> {
+  /** Image URL */
+  src?: string;
+  /** Alt text for image */
+  alt?: string;
+  /** Fallback initials (1-2 characters) */
+  initials?: string;
+  /** Avatar size */
+  size?: "sm" | "md" | "lg" | "xl";
+}
+
+export const Avatar = forwardRef<HTMLDivElement, AvatarProps>(
+  (
+    {
+      src,
+      alt = "",
+      initials = "",
+      size = "md",
+      className = "",
+      ...rest
+    },
+    ref,
+  ) => {
+    const [imgError, setImgError] = useState(false);
+
+    const handleError = useCallback(() => {
+      setImgError(true);
+    }, []);
+
+    const showImage = src && !imgError;
+    const displayInitials = initials.slice(0, 2).toUpperCase();
+
+    const classes = [
+      "strand-avatar",
+      `strand-avatar--${size}`,
+      className,
+    ]
+      .filter(Boolean)
+      .join(" ");
+
+    return (
+      <div ref={ref} className={classes} role="img" aria-label={alt || displayInitials} {...rest}>
+        {showImage ? (
+          <img
+            className="strand-avatar__img"
+            src={src}
+            alt={alt}
+            onError={handleError}
+          />
+        ) : (
+          <span className="strand-avatar__initials" aria-hidden="true">
+            {displayInitials}
+          </span>
+        )}
+      </div>
+    );
+  },
+);
+
+Avatar.displayName = "Avatar";