@emara/ui 1.1.0

package/components/ui/checkbox.tsx

@@ -0,0 +1,131 @@
+"use client";
+
+import { forwardRef, useId } from "react";
+import * as CheckboxPrimitive from "@radix-ui/react-checkbox";
+import { RiCheckLine, RiSubtractLine } from "@remixicon/react";
+import { cva, type VariantProps } from "class-variance-authority";
+
+import { cn } from "@/lib/utils";
+
+// Per docs/emara-ui-phase-2-components.md §1.
+
+const checkboxVariants = cva(
+  [
+    "peer shrink-0 rounded-sm border border-input bg-background",
+    "transition-colors",
+    "hover:border-foreground/40 data-[state=checked]:hover:bg-primary/90 data-[state=indeterminate]:hover:bg-primary/90",
+    "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 disabled:hover:border-input",
+    "data-[state=checked]:bg-primary data-[state=checked]:border-primary data-[state=checked]:text-primary-foreground",
+    "data-[state=indeterminate]:bg-primary data-[state=indeterminate]:border-primary data-[state=indeterminate]:text-primary-foreground",
+  ].join(" "),
+  {
+    variants: {
+      size: {
+        sm: "size-4",
+        md: "size-5",
+        lg: "size-6",
+      },
+      invalid: {
+        true: "border-destructive focus-visible:ring-destructive data-[state=checked]:bg-destructive data-[state=checked]:border-destructive data-[state=indeterminate]:bg-destructive data-[state=indeterminate]:border-destructive",
+        false: "",
+      },
+    },
+    defaultVariants: { size: "md", invalid: false },
+  },
+);
+
+const indicatorIconSize: Record<"sm" | "md" | "lg", string> = {
+  sm: "size-3",
+  md: "size-3.5",
+  lg: "size-4",
+};
+
+const labelSize: Record<"sm" | "md" | "lg", string> = {
+  sm: "text-xs",
+  md: "text-sm",
+  lg: "text-base",
+};
+
+const descriptionSize: Record<"sm" | "md" | "lg", string> = {
+  sm: "text-2xs",
+  md: "text-xs",
+  lg: "text-sm",
+};
+
+type CheckboxVariants = VariantProps<typeof checkboxVariants>;
+
+type CheckboxProps = Omit<React.ComponentPropsWithoutRef<typeof CheckboxPrimitive.Root>, "size"> &
+  CheckboxVariants & {
+    label?: React.ReactNode;
+    description?: React.ReactNode;
+  };
+
+const Checkbox = forwardRef<React.ElementRef<typeof CheckboxPrimitive.Root>, CheckboxProps>(
+  function Checkbox({ className, size = "md", invalid, label, description, id, ...props }, ref) {
+    const reactId = useId();
+    const checkboxId = id ?? reactId;
+    const descriptionId = description ? `${checkboxId}-description` : undefined;
+    const resolvedSize = size ?? "md";
+
+    const checkbox = (
+      <CheckboxPrimitive.Root
+        ref={ref}
+        id={checkboxId}
+        aria-invalid={invalid || undefined}
+        aria-describedby={descriptionId}
+        className={cn(checkboxVariants({ size, invalid }), className)}
+        {...props}
+      >
+        <CheckboxPrimitive.Indicator
+          className={cn("flex items-center justify-center text-current")}
+        >
+          {props.checked === "indeterminate" ? (
+            <RiSubtractLine className={indicatorIconSize[resolvedSize]} />
+          ) : (
+            <RiCheckLine className={indicatorIconSize[resolvedSize]} />
+          )}
+        </CheckboxPrimitive.Indicator>
+      </CheckboxPrimitive.Root>
+    );
+
+    if (!label && !description) return checkbox;
+
+    // When `label` is provided, render the full row pattern: checkbox + label + description.
+    return (
+      <div className="inline-flex items-start gap-2">
+        {checkbox}
+        <div className="space-y-0.5 leading-none">
+          {label ? (
+            <label
+              htmlFor={checkboxId}
+              className={cn(
+                "cursor-pointer font-medium select-none",
+                labelSize[resolvedSize],
+                props.disabled && "cursor-not-allowed opacity-50",
+              )}
+            >
+              {label}
+            </label>
+          ) : null}
+          {description ? (
+            <p
+              id={descriptionId}
+              className={cn(
+                "text-muted-foreground",
+                descriptionSize[resolvedSize],
+                props.disabled && "opacity-50",
+              )}
+            >
+              {description}
+            </p>
+          ) : null}
+        </div>
+      </div>
+    );
+  },
+);
+Checkbox.displayName = "Checkbox";
+
+export { Checkbox, checkboxVariants };
+export type { CheckboxProps };

package/components/ui/combobox.stories.tsx

@@ -0,0 +1,489 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { useState } from "react";
+import { RiGlobalLine } from "@remixicon/react";
+
+import {
+  Combobox,
+  ComboboxContent,
+  ComboboxGroup,
+  ComboboxInput,
+  ComboboxItem,
+  ComboboxList,
+  ComboboxSeparator,
+  ComboboxTrigger,
+} from "./combobox";
+
+const FRAMEWORKS = [
+  { value: "next", label: "Next.js" },
+  { value: "remix", label: "Remix" },
+  { value: "astro", label: "Astro" },
+  { value: "vite", label: "Vite" },
+  { value: "svelte", label: "SvelteKit" },
+  { value: "nuxt", label: "Nuxt" },
+];
+
+const COUNTRIES = [
+  { value: "ma", label: "Morocco" },
+  { value: "fr", label: "France" },
+  { value: "de", label: "Germany" },
+  { value: "us", label: "United States" },
+  { value: "jp", label: "Japan" },
+  { value: "br", label: "Brazil" },
+];
+
+const meta: Meta = {
+  title: "Forms/Combobox",
+  parameters: { layout: "centered" },
+};
+
+export default meta;
+type Story = StoryObj;
+
+export const Default: Story = {
+  render: () => {
+    const Wrapper = () => {
+      const [value, setValue] = useState("");
+      const selected = FRAMEWORKS.find((f) => f.value === value);
+      return (
+        <div className="w-64">
+          <Combobox value={value} onValueChange={setValue}>
+            <ComboboxTrigger placeholder="Pick a framework">{selected?.label}</ComboboxTrigger>
+            <ComboboxContent emptyMessage="No results.">
+              <ComboboxInput placeholder="Search frameworks…" />
+              <ComboboxList>
+                {FRAMEWORKS.map((f) => (
+                  <ComboboxItem key={f.value} value={f.value}>
+                    {f.label}
+                  </ComboboxItem>
+                ))}
+              </ComboboxList>
+            </ComboboxContent>
+          </Combobox>
+        </div>
+      );
+    };
+    return <Wrapper />;
+  },
+};
+
+export const Controlled: Story = {
+  render: () => {
+    const Wrapper = () => {
+      const [value, setValue] = useState("remix");
+      const selected = FRAMEWORKS.find((f) => f.value === value);
+      return (
+        <div className="w-64 space-y-2">
+          <Combobox value={value} onValueChange={setValue}>
+            <ComboboxTrigger placeholder="Framework" clearable>
+              {selected?.label}
+            </ComboboxTrigger>
+            <ComboboxContent emptyMessage="No results.">
+              <ComboboxInput />
+              <ComboboxList>
+                {FRAMEWORKS.map((f) => (
+                  <ComboboxItem key={f.value} value={f.value}>
+                    {f.label}
+                  </ComboboxItem>
+                ))}
+              </ComboboxList>
+            </ComboboxContent>
+          </Combobox>
+          <p className="text-muted-foreground text-xs">value: {JSON.stringify(value)}</p>
+        </div>
+      );
+    };
+    return <Wrapper />;
+  },
+};
+
+export const Clearable: Story = {
+  render: () => {
+    const Wrapper = () => {
+      const [value, setValue] = useState("next");
+      const selected = FRAMEWORKS.find((f) => f.value === value);
+      return (
+        <div className="w-64">
+          <Combobox value={value} onValueChange={setValue}>
+            <ComboboxTrigger placeholder="Pick a framework" clearable>
+              {selected?.label}
+            </ComboboxTrigger>
+            <ComboboxContent emptyMessage="No results.">
+              <ComboboxInput />
+              <ComboboxList>
+                {FRAMEWORKS.map((f) => (
+                  <ComboboxItem key={f.value} value={f.value}>
+                    {f.label}
+                  </ComboboxItem>
+                ))}
+              </ComboboxList>
+            </ComboboxContent>
+          </Combobox>
+        </div>
+      );
+    };
+    return <Wrapper />;
+  },
+};
+
+export const WithIconsAndDescriptions: Story = {
+  render: () => (
+    <div className="w-72">
+      <Combobox>
+        <ComboboxTrigger placeholder="Pick a country" />
+        <ComboboxContent emptyMessage="No matches.">
+          <ComboboxInput />
+          <ComboboxList>
+            {COUNTRIES.map((c) => (
+              <ComboboxItem
+                key={c.value}
+                value={c.value}
+                icon={<RiGlobalLine />}
+                description={`Code: ${c.value.toUpperCase()}`}
+              >
+                {c.label}
+              </ComboboxItem>
+            ))}
+          </ComboboxList>
+        </ComboboxContent>
+      </Combobox>
+    </div>
+  ),
+};
+
+export const Grouped: Story = {
+  render: () => (
+    <div className="w-64">
+      <Combobox>
+        <ComboboxTrigger placeholder="Pick a region" />
+        <ComboboxContent emptyMessage="No matches.">
+          <ComboboxInput />
+          <ComboboxList>
+            <ComboboxGroup heading="Africa">
+              <ComboboxItem value="ma">Morocco</ComboboxItem>
+              <ComboboxItem value="eg">Egypt</ComboboxItem>
+              <ComboboxItem value="ke">Kenya</ComboboxItem>
+            </ComboboxGroup>
+            <ComboboxSeparator />
+            <ComboboxGroup heading="Europe">
+              <ComboboxItem value="fr">France</ComboboxItem>
+              <ComboboxItem value="de">Germany</ComboboxItem>
+              <ComboboxItem value="es">Spain</ComboboxItem>
+            </ComboboxGroup>
+          </ComboboxList>
+        </ComboboxContent>
+      </Combobox>
+    </div>
+  ),
+};
+
+export const Invalid: Story = {
+  render: () => (
+    <div className="w-64">
+      <Combobox invalid>
+        <ComboboxTrigger placeholder="Required" />
+        <ComboboxContent emptyMessage="—">
+          <ComboboxInput />
+          <ComboboxList>
+            {FRAMEWORKS.slice(0, 3).map((f) => (
+              <ComboboxItem key={f.value} value={f.value}>
+                {f.label}
+              </ComboboxItem>
+            ))}
+          </ComboboxList>
+        </ComboboxContent>
+      </Combobox>
+    </div>
+  ),
+};
+
+export const Loading: Story = {
+  render: () => (
+    <div className="w-64">
+      <Combobox loading>
+        <ComboboxTrigger placeholder="Loading…" />
+      </Combobox>
+    </div>
+  ),
+};
+
+export const Disabled: Story = {
+  render: () => (
+    <div className="w-64">
+      <Combobox defaultValue="vite" disabled>
+        <ComboboxTrigger placeholder="Disabled" />
+      </Combobox>
+    </div>
+  ),
+};
+
+/**
+ * Multi-select mode. The trigger renders one pill per selected value;
+ * past 3 selections, additional items collapse into a "+N more" badge.
+ * Selecting an already-selected item deselects it and keeps the popover
+ * open so users can keep picking.
+ */
+export const Multiple: Story = {
+  render: () => {
+    const Wrapper = () => {
+      const [values, setValues] = useState<string[]>(["next", "vite"]);
+      const labelFor = (v: string) => FRAMEWORKS.find((f) => f.value === v)?.label ?? v;
+      return (
+        <div className="w-72 space-y-2">
+          <Combobox multiple value={values} onValueChange={setValues}>
+            <ComboboxTrigger placeholder="Pick frameworks" clearable getOptionLabel={labelFor} />
+            <ComboboxContent emptyMessage="No results.">
+              <ComboboxInput placeholder="Search…" />
+              <ComboboxList>
+                {FRAMEWORKS.map((f) => (
+                  <ComboboxItem key={f.value} value={f.value}>
+                    {f.label}
+                  </ComboboxItem>
+                ))}
+              </ComboboxList>
+            </ComboboxContent>
+          </Combobox>
+          <p className="text-muted-foreground text-xs">value: {JSON.stringify(values)}</p>
+        </div>
+      );
+    };
+    return <Wrapper />;
+  },
+};
+
+/**
+ * Multi-select with `maxSelected={3}`. Once three items are picked, the
+ * remaining unselected items become disabled. Already-selected items can
+ * still be toggled off.
+ */
+export const MultipleWithMaxSelected: Story = {
+  render: () => {
+    const Wrapper = () => {
+      const [values, setValues] = useState<string[]>([]);
+      const labelFor = (v: string) => FRAMEWORKS.find((f) => f.value === v)?.label ?? v;
+      return (
+        <div className="w-72">
+          <Combobox multiple value={values} onValueChange={setValues} maxSelected={3}>
+            <ComboboxTrigger placeholder="Pick up to 3 frameworks" getOptionLabel={labelFor} />
+            <ComboboxContent emptyMessage="No results.">
+              <ComboboxInput placeholder="Search…" />
+              <ComboboxList>
+                {FRAMEWORKS.map((f) => (
+                  <ComboboxItem key={f.value} value={f.value}>
+                    {f.label}
+                  </ComboboxItem>
+                ))}
+              </ComboboxList>
+            </ComboboxContent>
+          </Combobox>
+        </div>
+      );
+    };
+    return <Wrapper />;
+  },
+};
+
+/**
+ * Creatable: when the user types a search that doesn't match an existing
+ * option, a "+ Create '...' " row appears below the list. `onCreate` is
+ * the consumer's hook to add the new option to their data source AND
+ * (optionally) select it.
+ */
+export const Creatable: Story = {
+  render: () => {
+    const Wrapper = () => {
+      const [options, setOptions] = useState<{ value: string; label: string }[]>([
+        { value: "react", label: "React" },
+        { value: "vue", label: "Vue" },
+      ]);
+      const [value, setValue] = useState("");
+      const labelFor = (v: string) => options.find((o) => o.value === v)?.label ?? v;
+      return (
+        <div className="w-72 space-y-2">
+          <Combobox
+            value={value}
+            onValueChange={setValue}
+            creatable
+            onCreate={(q) => {
+              const slug = q.toLowerCase().replace(/\s+/g, "-");
+              setOptions((prev) => [...prev, { value: slug, label: q }]);
+              setValue(slug);
+            }}
+          >
+            <ComboboxTrigger placeholder="Pick or create a framework" getOptionLabel={labelFor}>
+              {labelFor(value)}
+            </ComboboxTrigger>
+            <ComboboxContent emptyMessage="No matches.">
+              <ComboboxInput placeholder="Type a new one…" />
+              <ComboboxList>
+                {options.map((o) => (
+                  <ComboboxItem key={o.value} value={o.value}>
+                    {o.label}
+                  </ComboboxItem>
+                ))}
+              </ComboboxList>
+            </ComboboxContent>
+          </Combobox>
+          <p className="text-muted-foreground text-xs">value: {JSON.stringify(value)}</p>
+        </div>
+      );
+    };
+    return <Wrapper />;
+  },
+};
+
+/**
+ * Creatable + multi-select. Consumer is responsible for both adding the
+ * new option to its data source AND appending the value to the selected
+ * array — the component does not mutate state in `onCreate`.
+ */
+export const CreatableMultiple: Story = {
+  render: () => {
+    const Wrapper = () => {
+      const [options, setOptions] = useState<{ value: string; label: string }[]>([
+        { value: "next", label: "Next.js" },
+        { value: "remix", label: "Remix" },
+      ]);
+      const [values, setValues] = useState<string[]>([]);
+      const labelFor = (v: string) => options.find((o) => o.value === v)?.label ?? v;
+      return (
+        <div className="w-72 space-y-2">
+          <Combobox
+            multiple
+            value={values}
+            onValueChange={setValues}
+            creatable
+            onCreate={(q) => {
+              const slug = q.toLowerCase().replace(/\s+/g, "-");
+              setOptions((prev) => [...prev, { value: slug, label: q }]);
+              setValues((prev) => [...prev, slug]);
+            }}
+          >
+            <ComboboxTrigger placeholder="Pick or create" getOptionLabel={labelFor} />
+            <ComboboxContent emptyMessage="No matches.">
+              <ComboboxInput placeholder="Type to filter or create…" />
+              <ComboboxList>
+                {options.map((o) => (
+                  <ComboboxItem key={o.value} value={o.value}>
+                    {o.label}
+                  </ComboboxItem>
+                ))}
+              </ComboboxList>
+            </ComboboxContent>
+          </Combobox>
+        </div>
+      );
+    };
+    return <Wrapper />;
+  },
+};
+
+/**
+ * Async option loading via `loadOptions`. The component handles debounce,
+ * race-condition guarding (stale responses are dropped), and auto-renders
+ * the returned options as items. Consumer just supplies the fetcher.
+ */
+export const AsyncLoadOptions: Story = {
+  render: () => {
+    type O = { value: string; label: string };
+    const ALL: O[] = [
+      { value: "next", label: "Next.js" },
+      { value: "remix", label: "Remix" },
+      { value: "astro", label: "Astro" },
+      { value: "vite", label: "Vite" },
+      { value: "svelte", label: "SvelteKit" },
+      { value: "nuxt", label: "Nuxt" },
+      { value: "qwik", label: "Qwik" },
+      { value: "solid", label: "SolidStart" },
+    ];
+    const fetcher = async (query: string): Promise<O[]> => {
+      // Pretend network: 300ms artificial delay.
+      await new Promise((r) => setTimeout(r, 300));
+      const q = query.toLowerCase();
+      return ALL.filter((o) => o.label.toLowerCase().includes(q));
+    };
+    return (
+      <div className="w-72">
+        <Combobox loadOptions={fetcher}>
+          <ComboboxTrigger placeholder="Search frameworks…" />
+          <ComboboxContent emptyMessage="No matches.">
+            <ComboboxInput placeholder="Type to search…" />
+          </ComboboxContent>
+        </Combobox>
+      </div>
+    );
+  },
+};
+
+/**
+ * `groupBy` partitions loaded options into auto-headed groups. Saves the
+ * boilerplate of writing `<ComboboxGroup>` manually around each region.
+ * Groups appear in first-seen insertion order — sort your options array
+ * if you want alphabetical ordering.
+ */
+export const AsyncGrouped: Story = {
+  render: () => {
+    type O = { value: string; label: string; region: string };
+    const ALL: O[] = [
+      { value: "ma", label: "Morocco", region: "Africa" },
+      { value: "eg", label: "Egypt", region: "Africa" },
+      { value: "ke", label: "Kenya", region: "Africa" },
+      { value: "fr", label: "France", region: "Europe" },
+      { value: "de", label: "Germany", region: "Europe" },
+      { value: "es", label: "Spain", region: "Europe" },
+      { value: "jp", label: "Japan", region: "Asia" },
+      { value: "kr", label: "South Korea", region: "Asia" },
+    ];
+    const fetcher = async (q: string): Promise<O[]> => {
+      await new Promise((r) => setTimeout(r, 150));
+      return ALL.filter((o) => o.label.toLowerCase().includes(q.toLowerCase()));
+    };
+    return (
+      <div className="w-72">
+        <Combobox loadOptions={fetcher} groupBy={(o) => (o as O).region}>
+          <ComboboxTrigger placeholder="Pick a country" />
+          <ComboboxContent emptyMessage="No matches.">
+            <ComboboxInput placeholder="Type to search…" />
+          </ComboboxContent>
+        </Combobox>
+      </div>
+    );
+  },
+};
+
+/**
+ * `keywords` on each item adds extra search terms beyond the value and
+ * rendered children. Type "nyc" to match New York, "windy" to match
+ * Chicago, etc. — none of those strings appear in the visible label.
+ */
+export const WithKeywords: Story = {
+  render: () => {
+    const CITIES: { value: string; label: string; keywords: string[] }[] = [
+      { value: "new-york", label: "New York", keywords: ["nyc", "ny", "big apple"] },
+      { value: "los-angeles", label: "Los Angeles", keywords: ["la", "city of angels"] },
+      { value: "chicago", label: "Chicago", keywords: ["chi", "windy city"] },
+      { value: "san-francisco", label: "San Francisco", keywords: ["sf", "the city", "bay area"] },
+    ];
+    const Wrapper = () => {
+      const [value, setValue] = useState("");
+      const selected = CITIES.find((c) => c.value === value);
+      return (
+        <div className="w-64">
+          <Combobox value={value} onValueChange={setValue}>
+            <ComboboxTrigger placeholder="Pick a city">{selected?.label}</ComboboxTrigger>
+            <ComboboxContent emptyMessage="No matching city.">
+              <ComboboxInput placeholder="Try 'nyc', 'la', 'windy'…" />
+              <ComboboxList>
+                {CITIES.map((c) => (
+                  <ComboboxItem key={c.value} value={c.value} keywords={c.keywords}>
+                    {c.label}
+                  </ComboboxItem>
+                ))}
+              </ComboboxList>
+            </ComboboxContent>
+          </Combobox>
+        </div>
+      );
+    };
+    return <Wrapper />;
+  },
+};