@emara/ui 1.1.0

package/components/ui/skeleton.stories.tsx

@@ -0,0 +1,131 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+
+import {
+  Skeleton,
+  SkeletonButton,
+  SkeletonCard,
+  SkeletonCircle,
+  SkeletonInput,
+  SkeletonTable,
+  SkeletonText,
+} from "./skeleton";
+
+const meta: Meta<typeof Skeleton> = {
+  title: "Foundations/Skeleton",
+  component: Skeleton,
+  parameters: { layout: "centered" },
+  argTypes: {
+    animation: { control: "select", options: ["pulse", "shimmer", "none"] },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Skeleton>;
+
+export const Default: Story = {
+  args: { className: "h-4 w-48" },
+};
+
+export const Animations: Story = {
+  render: () => (
+    <div className="w-96 space-y-4">
+      <div className="space-y-1">
+        <p className="text-muted-foreground text-xs">pulse</p>
+        <Skeleton animation="pulse" className="h-4 w-full" />
+      </div>
+      <div className="space-y-1">
+        <p className="text-muted-foreground text-xs">shimmer</p>
+        <Skeleton animation="shimmer" className="h-4 w-full" />
+      </div>
+      <div className="space-y-1">
+        <p className="text-muted-foreground text-xs">none</p>
+        <Skeleton animation="none" className="h-4 w-full" />
+      </div>
+    </div>
+  ),
+};
+
+export const Text: Story = {
+  render: () => (
+    <div className="w-96">
+      <SkeletonText lines={4} />
+    </div>
+  ),
+};
+
+export const Circles: Story = {
+  render: () => (
+    <div className="flex items-end gap-3">
+      <SkeletonCircle size="xs" />
+      <SkeletonCircle size="sm" />
+      <SkeletonCircle size="md" />
+      <SkeletonCircle size="lg" />
+      <SkeletonCircle size="xl" />
+      <SkeletonCircle size="2xl" />
+    </div>
+  ),
+};
+
+/**
+ * SkeletonCircle with the shimmer animation. Validates that the parent
+ * Skeleton's shimmer band (via `before:` pseudo-element) correctly clips
+ * to the circle shape and is visible against the base fill.
+ */
+export const CirclesWithShimmer: Story = {
+  render: () => (
+    <div className="flex items-end gap-3">
+      <SkeletonCircle size="sm" animation="shimmer" />
+      <SkeletonCircle size="md" animation="shimmer" />
+      <SkeletonCircle size="lg" animation="shimmer" />
+      <SkeletonCircle size="xl" animation="shimmer" />
+    </div>
+  ),
+};
+
+export const Buttons: Story = {
+  render: () => (
+    <div className="flex items-end gap-3">
+      <SkeletonButton size="xs" />
+      <SkeletonButton size="sm" />
+      <SkeletonButton size="default" />
+      <SkeletonButton size="lg" />
+      <SkeletonButton size="xl" />
+    </div>
+  ),
+};
+
+export const Inputs: Story = {
+  render: () => (
+    <div className="w-72 space-y-2">
+      <SkeletonInput size="xs" />
+      <SkeletonInput size="sm" />
+      <SkeletonInput size="md" />
+      <SkeletonInput size="lg" />
+      <SkeletonInput size="xl" />
+    </div>
+  ),
+};
+
+export const Card: Story = {
+  render: () => (
+    <div className="w-96">
+      <SkeletonCard />
+    </div>
+  ),
+};
+
+export const Table: Story = {
+  render: () => (
+    <div className="w-[40rem]">
+      <SkeletonTable rows={5} cols={4} />
+    </div>
+  ),
+};
+
+export const ShimmerLayout: Story = {
+  render: () => (
+    <div className="w-96">
+      <SkeletonCard animation="shimmer" />
+    </div>
+  ),
+};

package/components/ui/skeleton.tsx

@@ -0,0 +1,311 @@
+"use client";
+
+import { forwardRef } from "react";
+import { Slot } from "@radix-ui/react-slot";
+import { cva, type VariantProps } from "class-variance-authority";
+
+import { cn } from "@/lib/utils";
+
+// Per docs/emara-ui-phase-1-components.md §9.
+
+const skeletonVariants = cva("rounded-md bg-foreground/10", {
+  variants: {
+    animation: {
+      pulse: "animate-pulse",
+      shimmer: [
+        "relative overflow-hidden isolate",
+        // Sliding band — a contrasting tone sweeps across the base fill.
+        // Base is `bg-foreground/10`; the band is `foreground/35` so it's
+        // visibly darker in light mode and visibly lighter in dark mode.
+        // The keyframe `shimmer-slide` (in globals.css) animates translateX
+        // and the cascade flips direction for RTL.
+        "before:absolute before:inset-0 before:content-[''] before:z-10 before:pointer-events-none",
+        "before:bg-gradient-to-r before:from-transparent before:via-foreground/35 before:to-transparent",
+        "before:animate-[shimmer-slide_1.2s_linear_infinite]",
+      ].join(" "),
+      none: "",
+    },
+  },
+  defaultVariants: {
+    animation: "pulse",
+  },
+});
+
+type SkeletonVariants = VariantProps<typeof skeletonVariants>;
+
+type SkeletonProps = React.HTMLAttributes<HTMLDivElement> &
+  SkeletonVariants & {
+    asChild?: boolean;
+  };
+
+const Skeleton = forwardRef<HTMLDivElement, SkeletonProps>(function Skeleton(
+  { className, animation, asChild = false, ...props },
+  ref,
+) {
+  const Comp = asChild ? Slot : "div";
+  return (
+    <Comp
+      ref={ref}
+      aria-hidden="true"
+      className={cn(skeletonVariants({ animation }), className)}
+      {...props}
+    />
+  );
+});
+Skeleton.displayName = "Skeleton";
+
+// ============================================================================
+// Preset shapes (Emara additions). All are aria-hidden via the base Skeleton.
+// ============================================================================
+
+// --- SkeletonText -----------------------------------------------------------
+
+type SkeletonTextProps = Omit<SkeletonProps, "asChild"> & {
+  lines?: number;
+  /** Width of the last line as a fraction of full width. Default 0.6. */
+  lastLineWidth?: number;
+};
+
+// Pre-computed "realistic" widths for paragraphs. Repeats after this many lines.
+const TEXT_LINE_WIDTHS = ["w-full", "w-11/12", "w-full", "w-10/12", "w-full"];
+
+const SkeletonText = forwardRef<HTMLDivElement, SkeletonTextProps>(function SkeletonText(
+  { className, animation, lines = 3, lastLineWidth = 0.6, ...props },
+  ref,
+) {
+  const lastWidthStyle: React.CSSProperties = { width: `${Math.round(lastLineWidth * 100)}%` };
+  return (
+    <div ref={ref} aria-hidden="true" className={cn("space-y-2", className)} {...props}>
+      {Array.from({ length: Math.max(1, lines) }, (_, i) => {
+        const isLast = i === lines - 1 && lines > 1;
+        const widthClass = isLast
+          ? ""
+          : (TEXT_LINE_WIDTHS[i % TEXT_LINE_WIDTHS.length] ?? "w-full");
+        return (
+          <Skeleton
+            key={i}
+            animation={animation}
+            className={cn("h-4", widthClass)}
+            style={isLast ? lastWidthStyle : undefined}
+          />
+        );
+      })}
+    </div>
+  );
+});
+SkeletonText.displayName = "SkeletonText";
+
+// --- SkeletonCircle ---------------------------------------------------------
+
+type SkeletonCircleSize = "xs" | "sm" | "md" | "lg" | "xl" | "2xl";
+
+// Note: animation is intentionally NOT part of this variant set — the parent
+// <Skeleton> already supplies the right classes for pulse / shimmer / none
+// (including the relative+overflow-hidden+::before band that shimmer needs).
+// Duplicating animation here used to strip the shimmer styling, so the audit
+// flagged "shimmer doesn't work on SkeletonCircle".
+const skeletonCircleVariants = cva("rounded-full", {
+  variants: {
+    size: {
+      xs: "size-6",
+      sm: "size-8",
+      md: "size-10",
+      lg: "size-12",
+      xl: "size-16",
+      "2xl": "size-24",
+    },
+  },
+  defaultVariants: { size: "md" },
+});
+
+type SkeletonCircleProps = Omit<React.HTMLAttributes<HTMLDivElement>, "children"> & {
+  size?: SkeletonCircleSize;
+  animation?: SkeletonVariants["animation"];
+};
+
+const SkeletonCircle = forwardRef<HTMLDivElement, SkeletonCircleProps>(function SkeletonCircle(
+  { className, size, animation = "pulse", ...props },
+  ref,
+) {
+  return (
+    <Skeleton
+      ref={ref}
+      animation={animation}
+      className={cn(skeletonCircleVariants({ size }), className)}
+      {...props}
+    />
+  );
+});
+SkeletonCircle.displayName = "SkeletonCircle";
+
+// --- SkeletonButton ---------------------------------------------------------
+
+type SkeletonButtonSize = "xs" | "sm" | "default" | "lg" | "xl";
+
+const skeletonButtonVariants = cva("rounded-md bg-foreground/10", {
+  variants: {
+    size: {
+      xs: "h-7",
+      sm: "h-8",
+      default: "h-9",
+      lg: "h-10",
+      xl: "h-12",
+    },
+    width: {
+      auto: "w-24",
+      full: "w-full",
+    },
+  },
+  defaultVariants: { size: "default", width: "auto" },
+});
+
+type SkeletonButtonProps = Omit<React.HTMLAttributes<HTMLDivElement>, "children"> & {
+  size?: SkeletonButtonSize;
+  width?: "auto" | "full";
+  animation?: SkeletonVariants["animation"];
+};
+
+const SkeletonButton = forwardRef<HTMLDivElement, SkeletonButtonProps>(function SkeletonButton(
+  { className, size, width, animation = "pulse", ...props },
+  ref,
+) {
+  return (
+    <Skeleton
+      ref={ref}
+      animation={animation}
+      className={cn(skeletonButtonVariants({ size, width }), className)}
+      {...props}
+    />
+  );
+});
+SkeletonButton.displayName = "SkeletonButton";
+
+// --- SkeletonInput ----------------------------------------------------------
+
+type SkeletonInputSize = "xs" | "sm" | "md" | "lg" | "xl";
+
+const skeletonInputVariants = cva("rounded-md bg-foreground/10 w-full", {
+  variants: {
+    size: {
+      xs: "h-7",
+      sm: "h-8",
+      md: "h-9",
+      lg: "h-10",
+      xl: "h-12",
+    },
+  },
+  defaultVariants: { size: "md" },
+});
+
+type SkeletonInputProps = Omit<React.HTMLAttributes<HTMLDivElement>, "children"> & {
+  size?: SkeletonInputSize;
+  animation?: SkeletonVariants["animation"];
+};
+
+const SkeletonInput = forwardRef<HTMLDivElement, SkeletonInputProps>(function SkeletonInput(
+  { className, size, animation = "pulse", ...props },
+  ref,
+) {
+  return (
+    <Skeleton
+      ref={ref}
+      animation={animation}
+      className={cn(skeletonInputVariants({ size }), className)}
+      {...props}
+    />
+  );
+});
+SkeletonInput.displayName = "SkeletonInput";
+
+// --- SkeletonCard -----------------------------------------------------------
+
+type SkeletonCardProps = Omit<React.HTMLAttributes<HTMLDivElement>, "children"> & {
+  /** Show the header section (title + description). Default true. */
+  header?: boolean;
+  /** Number of body lines. Default 3. */
+  lines?: number;
+  animation?: SkeletonVariants["animation"];
+};
+
+const SkeletonCard = forwardRef<HTMLDivElement, SkeletonCardProps>(function SkeletonCard(
+  { className, header = true, lines = 3, animation = "pulse", ...props },
+  ref,
+) {
+  return (
+    <div
+      ref={ref}
+      aria-hidden="true"
+      className={cn("border-border space-y-4 rounded-md border p-4", className)}
+      {...props}
+    >
+      {header ? (
+        <div className="space-y-2">
+          <Skeleton animation={animation} className="h-5 w-2/5" />
+          <Skeleton animation={animation} className="h-4 w-3/5" />
+        </div>
+      ) : null}
+      <SkeletonText animation={animation} lines={lines} />
+    </div>
+  );
+});
+SkeletonCard.displayName = "SkeletonCard";
+
+// --- SkeletonTable ----------------------------------------------------------
+
+type SkeletonTableProps = Omit<React.HTMLAttributes<HTMLDivElement>, "children"> & {
+  rows?: number;
+  cols?: number;
+  animation?: SkeletonVariants["animation"];
+};
+
+const SkeletonTable = forwardRef<HTMLDivElement, SkeletonTableProps>(function SkeletonTable(
+  { className, rows = 5, cols = 4, animation = "pulse", ...props },
+  ref,
+) {
+  return (
+    <div ref={ref} aria-hidden="true" className={cn("space-y-2", className)} {...props}>
+      {/* Header row */}
+      <div
+        className="grid gap-3"
+        style={{ gridTemplateColumns: `repeat(${cols}, minmax(0, 1fr))` }}
+      >
+        {Array.from({ length: cols }, (_, c) => (
+          <Skeleton key={`h-${c}`} animation={animation} className="h-4" />
+        ))}
+      </div>
+      {/* Body rows */}
+      {Array.from({ length: rows }, (_, r) => (
+        <div
+          key={r}
+          className="grid gap-3"
+          style={{ gridTemplateColumns: `repeat(${cols}, minmax(0, 1fr))` }}
+        >
+          {Array.from({ length: cols }, (_, c) => (
+            <Skeleton key={`${r}-${c}`} animation={animation} className="h-4" />
+          ))}
+        </div>
+      ))}
+    </div>
+  );
+});
+SkeletonTable.displayName = "SkeletonTable";
+
+export {
+  Skeleton,
+  SkeletonText,
+  SkeletonCircle,
+  SkeletonButton,
+  SkeletonInput,
+  SkeletonCard,
+  SkeletonTable,
+  skeletonVariants,
+};
+export type {
+  SkeletonProps,
+  SkeletonTextProps,
+  SkeletonCircleProps,
+  SkeletonButtonProps,
+  SkeletonInputProps,
+  SkeletonCardProps,
+  SkeletonTableProps,
+};

package/components/ui/switch.stories.tsx

@@ -0,0 +1,74 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { RiMoonLine, RiSunLine } from "@remixicon/react";
+
+import { Switch } from "./switch";
+
+const meta: Meta<typeof Switch> = {
+  title: "Forms/Switch",
+  component: Switch,
+  parameters: { layout: "centered" },
+  argTypes: {
+    size: { control: "select", options: ["sm", "md", "lg"] },
+    loading: { control: "boolean" },
+    disabled: { control: "boolean" },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Switch>;
+
+export const Default: Story = {};
+
+export const Sizes: Story = {
+  render: () => (
+    <div className="flex items-center gap-4">
+      <Switch size="sm" defaultChecked />
+      <Switch size="md" defaultChecked />
+      <Switch size="lg" defaultChecked />
+    </div>
+  ),
+};
+
+export const States: Story = {
+  render: () => (
+    <div className="grid grid-cols-2 gap-3 text-sm">
+      <span>off</span>
+      <Switch />
+      <span>on</span>
+      <Switch defaultChecked />
+      <span>disabled off</span>
+      <Switch disabled />
+      <span>disabled on</span>
+      <Switch disabled defaultChecked />
+      <span>loading</span>
+      <Switch loading defaultChecked />
+    </div>
+  ),
+};
+
+export const PairedWithLabel: Story = {
+  render: () => (
+    <div className="flex items-center gap-3">
+      <Switch id="airplane" />
+      <label htmlFor="airplane" className="cursor-pointer text-sm font-medium">
+        Airplane mode
+      </label>
+    </div>
+  ),
+};
+
+export const WithIcons: Story = {
+  render: () => (
+    <Switch
+      defaultChecked
+      size="lg"
+      onIcon={<RiMoonLine />}
+      offIcon={<RiSunLine />}
+      aria-label="Theme"
+    />
+  ),
+};
+
+export const WithSideLabels: Story = {
+  render: () => <Switch defaultChecked size="lg" onLabel="ON" offLabel="OFF" aria-label="Power" />,
+};

package/components/ui/switch.tsx

@@ -0,0 +1,186 @@
+"use client";
+
+import { forwardRef } from "react";
+import * as SwitchPrimitive from "@radix-ui/react-switch";
+import { RiLoader2Line } from "@remixicon/react";
+import { cva, type VariantProps } from "class-variance-authority";
+
+import { cn } from "@/lib/utils";
+
+// Per docs/emara-ui-phase-2-components.md §3.
+
+const switchRootVariants = cva(
+  [
+    "peer inline-flex shrink-0 cursor-pointer items-center rounded-full",
+    "border border-transparent transition-colors",
+    "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background",
+    "disabled:cursor-not-allowed disabled:opacity-50",
+    "data-[state=checked]:bg-primary",
+    "data-[state=unchecked]:bg-input",
+    "aria-busy:cursor-progress",
+  ].join(" "),
+  {
+    variants: {
+      size: {
+        // [track width × height], thumb size handled via the thumb's variants.
+        // Track widths leave enough room for short side-labels in the empty
+        // half (~22px at md, ~26px at lg).
+        sm: "h-5 w-10 px-0.5",
+        md: "h-6 w-12 px-0.5",
+        lg: "h-7 w-16 px-0.5",
+      },
+    },
+    defaultVariants: { size: "md" },
+  },
+);
+
+const switchThumbVariants = cva(
+  [
+    "pointer-events-none block rounded-full bg-background shadow-sm",
+    "transition-transform duration-fast",
+    // RTL: in `dir="rtl"` the "checked" position is on the visual start
+    // (LTR right == RTL left). Use a CSS variable so the transform flips.
+    "translate-x-0",
+  ].join(" "),
+  {
+    variants: {
+      size: {
+        // Translation = (track width - thumb size - 2 × px-0.5).
+        // sm: 40 - 16 - 4 = 20 → translate-x-5
+        // md: 48 - 20 - 4 = 24 → translate-x-6
+        // lg: 64 - 24 - 4 = 36 → translate-x-9
+        sm: "size-4 data-[state=checked]:translate-x-5 rtl:data-[state=checked]:-translate-x-5",
+        md: "size-5 data-[state=checked]:translate-x-6 rtl:data-[state=checked]:-translate-x-6",
+        lg: "size-6 data-[state=checked]:translate-x-9 rtl:data-[state=checked]:-translate-x-9",
+      },
+    },
+    defaultVariants: { size: "md" },
+  },
+);
+
+const thumbIconSize: Record<"sm" | "md" | "lg", string> = {
+  sm: "size-2.5",
+  md: "size-3",
+  lg: "size-3.5",
+};
+
+// Side-label sizes are intentionally **sub-canonical** (below the type-scale's
+// `--text-2xs` step at 11px) — they're decorative micro-labels that sit inside
+// the empty half of the track, not body text. Per design-tokens §4.2's note on
+// sub-canonical micro-labels: arbitrary px values are allowed here precisely
+// because these aren't part of the readable type scale. No `tracking-wide`
+// — it would expand the text and clip it against the track edge.
+const sideLabelSize: Record<"sm" | "md" | "lg", string> = {
+  sm: "text-[8px]",
+  md: "text-[9px]",
+  lg: "text-[10px]",
+};
+
+type SwitchVariants = VariantProps<typeof switchRootVariants>;
+
+type SwitchProps = Omit<React.ComponentPropsWithoutRef<typeof SwitchPrimitive.Root>, "size"> &
+  SwitchVariants & {
+    loading?: boolean;
+    onIcon?: React.ReactNode;
+    offIcon?: React.ReactNode;
+    onLabel?: string;
+    offLabel?: string;
+  };
+
+const Switch = forwardRef<React.ElementRef<typeof SwitchPrimitive.Root>, SwitchProps>(
+  function Switch(
+    {
+      className,
+      size = "md",
+      loading = false,
+      onIcon,
+      offIcon,
+      onLabel,
+      offLabel,
+      disabled,
+      checked,
+      defaultChecked,
+      ...props
+    },
+    ref,
+  ) {
+    const resolvedSize = size ?? "md";
+    const isDisabled = disabled || loading;
+    // exactOptionalPropertyTypes: explicitly omit `checked`/`defaultChecked`
+    // when undefined rather than passing through.
+    const controlProps: Pick<
+      React.ComponentPropsWithoutRef<typeof SwitchPrimitive.Root>,
+      "checked" | "defaultChecked"
+    > = {};
+    if (checked !== undefined) controlProps.checked = checked;
+    if (defaultChecked !== undefined) controlProps.defaultChecked = defaultChecked;
+
+    return (
+      <SwitchPrimitive.Root
+        ref={ref}
+        disabled={isDisabled}
+        aria-busy={loading || undefined}
+        {...controlProps}
+        className={cn(switchRootVariants({ size }), "relative", className)}
+        {...props}
+      >
+        {/* Optional inline side-labels. The Root carries `data-state`; child
+        spans react via the `in-data-[state=...]` Tailwind v4 modifier so the
+        label that's NOT covered by the thumb is the one visible:
+        - on  → thumb at end → ON label appears at start
+        - off → thumb at start → OFF label appears at end
+        Pointer-events-none so the labels never block the toggle. */}
+        {onLabel ? (
+          <span
+            aria-hidden="true"
+            className={cn(
+              // Sit at the start side (empty when on), vertically centered.
+              "text-primary-foreground pointer-events-none absolute inset-y-0 start-1 inline-flex items-center leading-none font-semibold uppercase select-none",
+              sideLabelSize[resolvedSize],
+              "opacity-0 in-data-[state=checked]:opacity-100",
+            )}
+          >
+            {onLabel}
+          </span>
+        ) : null}
+        {offLabel ? (
+          <span
+            aria-hidden="true"
+            className={cn(
+              // Sit at the end side (empty when off), vertically centered.
+              "text-muted-foreground pointer-events-none absolute inset-y-0 end-1 inline-flex items-center leading-none font-semibold uppercase select-none",
+              sideLabelSize[resolvedSize],
+              "opacity-100 in-data-[state=checked]:opacity-0",
+            )}
+          >
+            {offLabel}
+          </span>
+        ) : null}
+
+        <SwitchPrimitive.Thumb className={cn(switchThumbVariants({ size }))}>
+          {/* Thumb-internal slot: spinner during loading, otherwise on/off icon
+          driven by the parent's data-state (peer would be cleaner but the
+          Thumb's own [data-state] does the same job at the Radix level). */}
+          <span className="text-foreground/70 flex h-full w-full items-center justify-center [&_svg]:size-3 [&_svg]:shrink-0">
+            {loading ? (
+              <RiLoader2Line className={cn(thumbIconSize[resolvedSize], "animate-spin")} />
+            ) : (
+              <>
+                {onIcon ? (
+                  <span className="hidden in-data-[state=checked]:inline-flex">{onIcon}</span>
+                ) : null}
+                {offIcon ? (
+                  <span className="inline-flex in-data-[state=checked]:hidden">{offIcon}</span>
+                ) : null}
+              </>
+            )}
+          </span>
+        </SwitchPrimitive.Thumb>
+      </SwitchPrimitive.Root>
+    );
+  },
+);
+Switch.displayName = "Switch";
+
+export { Switch, switchRootVariants, switchThumbVariants };
+export type { SwitchProps };