@cl-light-ds/ui 0.2.0 → 0.3.0

package/src/components/item/CHANGELOG.md

@@ -1,27 +1,27 @@
-# Changelog
-
-All notable changes to the `Item` component family (`Item`, `ItemGroup`, `ItemSeparator`, `ItemHeader`, `ItemFooter`, `ItemMedia`, `ItemContent`, `ItemTitle`, `ItemDescription`, `ItemActions`) are documented in this file.
-
-## 2026-09-10 — Figma alignment (ClickLearn Lightning Design Library, node `2329-7472`)
-
-Figma documents Item across four pages: Variants (Default, Outline, Muted), Sizes (Small, Large, Header), States (Default, Hover, Focus, Disabled), and Contents (Tail Icon, Tail Button, Lead Icon, Lead Image).
-
-### Fixed
-
-- Updated `@figmaUrl` from the old Bejamas file to the ClickLearn Lightning Design Library link.
-- Removed a dead, redundant `rounded-md` — `rounded-lg` (added afterward in the same class string) always won anyway, same class of cleanup already done on Dialog/HoverCard/Input/TooltipContent.
-- Removed a broken hover selector, `[a]:hover:bg-muted` — invalid Tailwind arbitrary-variant syntax (missing `&`), effectively dead/no-op. Per the standing project direction to skip hover states ("ignore hover states, they are not necessary... I will delete from figma"), removed rather than fixed into a working hover state.
-- Removed dead, unreachable `group-data-[size=xs]/item:...` selectors in `ItemMedia`/`ItemContent`/`ItemDescription` and `has-data-[size=xs]:...` in `ItemGroup` — these referenced a size value that has never existed in `Item`'s own `size` prop type and isn't documented in Figma either; pure leftover dead code.
-
-### Added
-
-- **Focus state**: `has-[:focus-visible]:border-ring has-[:focus-visible]:ring-3 has-[:focus-visible]:ring-ring/50` on the root — Figma shows a border+glow-ring treatment on the whole item (ring hex confirmed `#5f9de6` = `--ring`; the baked-in glow color Figma shows, `#afcef3`, is just `--ring` at ~50% opacity over white, confirming this is the same `ring-3 ring-ring/50` idiom used everywhere else, e.g. `HoverCardContent`). Since `Item`'s root is a plain non-focusable `<div>`, this activates whenever a focusable descendant (e.g. an action button) receives keyboard focus.
-- **`disabled` prop** (new, `boolean`, default `false`): sets `aria-disabled="true"` + `data-disabled` on the root, styled via `data-[disabled=true]:bg-muted data-[disabled=true]:pointer-events-none` — matches Figma's Disabled state (a real `bg-muted` swap, not an opacity fade, same category as the Checkbox/Input disabled fixes). Scope note: this only styles/blocks-interaction on the `Item` root itself — it does not automatically disable nested interactive children (e.g. an `ItemActions` button); consumers should still set `disabled` on those separately, as shown in the new JSDoc example.
-- **`size="header"`** (new): Figma's third documented size is a fundamentally different vertical/card layout — full-width square media on top, title/description below, no trailing action. `Item`'s `flex-wrap`/`items-center` row layout is now driven entirely per-size (`default`/`sm` stay row-based; `header` switches to `flex-col items-start gap-4 p-4`), and `ItemMedia`'s `image` variant grows to a full-width square (`w-full aspect-square`, canceling the row-oriented baseline nudge) whenever the parent `Item` has `data-size="header"`.
-
-### Notes
-
-- Variants (`default`/`outline`/`muted`) already matched Figma's three variants exactly — no change needed.
-- Lead Icon / Lead Image / Tail Button content compositions were already fully achievable via the existing `ItemMedia`/`ItemActions` primitives.
-- **Tail Icon** (a trailing chevron, no lead media) is already achievable today via `<ItemActions><ChevronRight /></ItemActions>` — no new prop needed, just added a storybook example since it wasn't previously demonstrated.
-- Figma's "Small"/"Large" size names correspond to the code's existing `sm`/`default` tiers respectively — same recurring size-naming situation as Accordion/Checkbox/Input, not renamed here.
+# Changelog
+
+All notable changes to the `Item` component family (`Item`, `ItemGroup`, `ItemSeparator`, `ItemHeader`, `ItemFooter`, `ItemMedia`, `ItemContent`, `ItemTitle`, `ItemDescription`, `ItemActions`) are documented in this file.
+
+## 2026-09-10 — Figma alignment (ClickLearn Lightning Design Library, node `2329-7472`)
+
+Figma documents Item across four pages: Variants (Default, Outline, Muted), Sizes (Small, Large, Header), States (Default, Hover, Focus, Disabled), and Contents (Tail Icon, Tail Button, Lead Icon, Lead Image).
+
+### Fixed
+
+- Updated `@figmaUrl` from the old Bejamas file to the ClickLearn Lightning Design Library link.
+- Removed a dead, redundant `rounded-md` — `rounded-lg` (added afterward in the same class string) always won anyway, same class of cleanup already done on Dialog/HoverCard/Input/TooltipContent.
+- Removed a broken hover selector, `[a]:hover:bg-muted` — invalid Tailwind arbitrary-variant syntax (missing `&`), effectively dead/no-op. Per the standing project direction to skip hover states ("ignore hover states, they are not necessary... I will delete from figma"), removed rather than fixed into a working hover state.
+- Removed dead, unreachable `group-data-[size=xs]/item:...` selectors in `ItemMedia`/`ItemContent`/`ItemDescription` and `has-data-[size=xs]:...` in `ItemGroup` — these referenced a size value that has never existed in `Item`'s own `size` prop type and isn't documented in Figma either; pure leftover dead code.
+
+### Added
+
+- **Focus state**: `has-[:focus-visible]:border-ring has-[:focus-visible]:ring-3 has-[:focus-visible]:ring-ring/50` on the root — Figma shows a border+glow-ring treatment on the whole item (ring hex confirmed `#5f9de6` = `--ring`; the baked-in glow color Figma shows, `#afcef3`, is just `--ring` at ~50% opacity over white, confirming this is the same `ring-3 ring-ring/50` idiom used everywhere else, e.g. `HoverCardContent`). Since `Item`'s root is a plain non-focusable `<div>`, this activates whenever a focusable descendant (e.g. an action button) receives keyboard focus.
+- **`disabled` prop** (new, `boolean`, default `false`): sets `aria-disabled="true"` + `data-disabled` on the root, styled via `data-[disabled=true]:bg-muted data-[disabled=true]:pointer-events-none` — matches Figma's Disabled state (a real `bg-muted` swap, not an opacity fade, same category as the Checkbox/Input disabled fixes). Scope note: this only styles/blocks-interaction on the `Item` root itself — it does not automatically disable nested interactive children (e.g. an `ItemActions` button); consumers should still set `disabled` on those separately, as shown in the new JSDoc example.
+- **`size="header"`** (new): Figma's third documented size is a fundamentally different vertical/card layout — full-width square media on top, title/description below, no trailing action. `Item`'s `flex-wrap`/`items-center` row layout is now driven entirely per-size (`default`/`sm` stay row-based; `header` switches to `flex-col items-start gap-4 p-4`), and `ItemMedia`'s `image` variant grows to a full-width square (`w-full aspect-square`, canceling the row-oriented baseline nudge) whenever the parent `Item` has `data-size="header"`.
+
+### Notes
+
+- Variants (`default`/`outline`/`muted`) already matched Figma's three variants exactly — no change needed.
+- Lead Icon / Lead Image / Tail Button content compositions were already fully achievable via the existing `ItemMedia`/`ItemActions` primitives.
+- **Tail Icon** (a trailing chevron, no lead media) is already achievable today via `<ItemActions><ChevronRight /></ItemActions>` — no new prop needed, just added a storybook example since it wasn't previously demonstrated.
+- Figma's "Small"/"Large" size names correspond to the code's existing `sm`/`default` tiers respectively — same recurring size-naming situation as Accordion/Checkbox/Input, not renamed here.

package/src/components/item/Item.astro

@@ -1,122 +1,122 @@
----
-/**
- * @component Item
- * @title Item
- * @description A versatile component for displaying any content, combining elements like title, description, media, and actions.
- * @figmaUrl https://www.figma.com/design/qXkzdqZ3QPQqgckU3AwIAH/ClickLearn-Lightning-Design-Library?node-id=2329-7472
- *
- * @preview
- *
- * <div class="flex w-full max-w-md flex-col gap-6">
- *   <Item variant="outline">
- *     <ItemContent>
- *       <ItemTitle>Basic Item</ItemTitle>
- *       <ItemDescription>A simple item with title and description.</ItemDescription>
- *     </ItemContent>
- *     <ItemActions><Button variant="outline" size="sm">Action</Button></ItemActions>
- *   </Item>
- * </div>
- *
- * @usage
- *
- * ```astro nocollapse
- * ---
- * import { Item, ItemContent, ItemTitle, ItemDescription, ItemActions, ItemMedia } from '@bejamas/ui/components/item';
- * ---
- *
- * <Item variant="outline">
- *   <ItemContent>
- *     <ItemTitle>Basic Item</ItemTitle>
- *     <ItemDescription>A simple item.</ItemDescription>
- *   </ItemContent>
- *   <ItemActions>
- *     <Button variant="outline" size="sm">Action</Button>
- *   </ItemActions>
- * </Item>
- * ```
- *
- * @examples
- *
- * ### Header size
- *
- * <Item variant="outline" size="header" class="max-w-xs">
- *   <ItemMedia mediaVariant="image">
- *     <img src="https://gradient.bejamas.com/presets/bejamas/marine.png" alt="" />
- *   </ItemMedia>
- *   <ItemContent>
- *     <ItemTitle>Security Alert</ItemTitle>
- *     <ItemDescription>A simple item with title and description.</ItemDescription>
- *   </ItemContent>
- * </Item>
- *
- * ### Disabled
- *
- * <Item variant="outline" disabled>
- *   <ItemContent>
- *     <ItemTitle>Basic Item</ItemTitle>
- *     <ItemDescription>A simple item with title and description.</ItemDescription>
- *   </ItemContent>
- *   <ItemActions><Button variant="outline" size="sm" disabled>Action</Button></ItemActions>
- * </Item>
- */
-
-import type { HTMLAttributes } from "astro/types";
-import { cva } from "class-variance-authority";
-import { cn } from "@cl-light-ds/ui/lib/utils";
-
-type ItemRootVariant = "default" | "outline" | "muted";
-type ItemRootSize = "default" | "sm" | "header";
-
-interface Props extends HTMLAttributes<"div"> {
-  variant?: ItemRootVariant;
-  size?: ItemRootSize;
-  disabled?: boolean;
-  class?: string;
-}
-
-const {
-  class: className = "",
-  variant = "default",
-  size = "default",
-  disabled = false,
-  ...rest
-} = Astro.props as Props;
-
-const itemVariants = cva(
-  "group/item flex outline-none transition-colors",
-  {
-    variants: {
-      variant: {
-        default: "border-transparent",
-        outline: "border-border",
-        muted: "bg-muted/50 border-transparent",
-      },
-      size: {
-        default: "flex-row flex-wrap items-center gap-3.5 px-4 py-3.5",
-        sm: "flex-row flex-wrap items-center gap-2.5 px-3 py-2.5",
-        header: "flex-col items-start gap-4 p-4",
-      },
-    },
-    defaultVariants: {
-      variant: "default",
-      size: "default",
-    },
-  },
-);
----
-
-<div
-  {...rest}
-  data-slot="item"
-  data-variant={variant}
-  data-size={size}
-  data-disabled={disabled}
-  aria-disabled={disabled ? "true" : undefined}
-  class={cn(
-    "border text-sm rounded-lg has-[:focus-visible]:border-ring has-[:focus-visible]:ring-3 has-[:focus-visible]:ring-ring/50 data-[disabled=true]:bg-muted data-[disabled=true]:pointer-events-none",
-    itemVariants({ variant, size }),
-    className,
-  )}
->
-  <slot />
-</div>
+---
+/**
+ * @component Item
+ * @title Item
+ * @description A versatile component for displaying any content, combining elements like title, description, media, and actions.
+ * @figmaUrl https://www.figma.com/design/qXkzdqZ3QPQqgckU3AwIAH/ClickLearn-Lightning-Design-Library?node-id=2329-7472
+ *
+ * @preview
+ *
+ * <div class="flex w-full max-w-md flex-col gap-6">
+ *   <Item variant="outline">
+ *     <ItemContent>
+ *       <ItemTitle>Basic Item</ItemTitle>
+ *       <ItemDescription>A simple item with title and description.</ItemDescription>
+ *     </ItemContent>
+ *     <ItemActions><Button variant="outline" size="sm">Action</Button></ItemActions>
+ *   </Item>
+ * </div>
+ *
+ * @usage
+ *
+ * ```astro nocollapse
+ * ---
+ * import { Item, ItemContent, ItemTitle, ItemDescription, ItemActions, ItemMedia } from '@bejamas/ui/components/item';
+ * ---
+ *
+ * <Item variant="outline">
+ *   <ItemContent>
+ *     <ItemTitle>Basic Item</ItemTitle>
+ *     <ItemDescription>A simple item.</ItemDescription>
+ *   </ItemContent>
+ *   <ItemActions>
+ *     <Button variant="outline" size="sm">Action</Button>
+ *   </ItemActions>
+ * </Item>
+ * ```
+ *
+ * @examples
+ *
+ * ### Header size
+ *
+ * <Item variant="outline" size="header" class="max-w-xs">
+ *   <ItemMedia mediaVariant="image">
+ *     <img src="https://gradient.bejamas.com/presets/bejamas/marine.png" alt="" />
+ *   </ItemMedia>
+ *   <ItemContent>
+ *     <ItemTitle>Security Alert</ItemTitle>
+ *     <ItemDescription>A simple item with title and description.</ItemDescription>
+ *   </ItemContent>
+ * </Item>
+ *
+ * ### Disabled
+ *
+ * <Item variant="outline" disabled>
+ *   <ItemContent>
+ *     <ItemTitle>Basic Item</ItemTitle>
+ *     <ItemDescription>A simple item with title and description.</ItemDescription>
+ *   </ItemContent>
+ *   <ItemActions><Button variant="outline" size="sm" disabled>Action</Button></ItemActions>
+ * </Item>
+ */
+
+import type { HTMLAttributes } from "astro/types";
+import { cva } from "class-variance-authority";
+import { cn } from "@cl-light-ds/ui/lib/utils";
+
+type ItemRootVariant = "default" | "outline" | "muted";
+type ItemRootSize = "default" | "sm" | "header";
+
+interface Props extends HTMLAttributes<"div"> {
+  variant?: ItemRootVariant;
+  size?: ItemRootSize;
+  disabled?: boolean;
+  class?: string;
+}
+
+const {
+  class: className = "",
+  variant = "default",
+  size = "default",
+  disabled = false,
+  ...rest
+} = Astro.props as Props;
+
+const itemVariants = cva(
+  "group/item flex outline-none transition-colors",
+  {
+    variants: {
+      variant: {
+        default: "border-transparent",
+        outline: "border-border",
+        muted: "bg-muted/50 border-transparent",
+      },
+      size: {
+        default: "flex-row flex-wrap items-center gap-3.5 px-4 py-3.5",
+        sm: "flex-row flex-wrap items-center gap-2.5 px-3 py-2.5",
+        header: "flex-col items-start gap-4 p-4",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+      size: "default",
+    },
+  },
+);
+---
+
+<div
+  {...rest}
+  data-slot="item"
+  data-variant={variant}
+  data-size={size}
+  data-disabled={disabled}
+  aria-disabled={disabled ? "true" : undefined}
+  class={cn(
+    "border text-sm rounded-lg has-[:focus-visible]:border-ring has-[:focus-visible]:ring-3 has-[:focus-visible]:ring-ring/50 data-[disabled=true]:bg-muted data-[disabled=true]:pointer-events-none",
+    itemVariants({ variant, size }),
+    className,
+  )}
+>
+  <slot />
+</div>

package/src/components/item/ItemActions.astro

@@ -1,21 +1,21 @@
----
-import { cn } from "@cl-light-ds/ui/lib/utils";
-import type { HTMLAttributes } from "astro/types";
-
-interface Props extends HTMLAttributes<"div"> {
-  class?: string;
-}
-
-const {
-  class: className = "",
-  ...rest
-} = Astro.props as Props;
----
-
-<div
-  {...rest}
-  data-slot="item-actions"
-  class={cn("gap-2 flex items-center", className)}
->
-  <slot />
-</div>
+---
+import { cn } from "@cl-light-ds/ui/lib/utils";
+import type { HTMLAttributes } from "astro/types";
+
+interface Props extends HTMLAttributes<"div"> {
+  class?: string;
+}
+
+const {
+  class: className = "",
+  ...rest
+} = Astro.props as Props;
+---
+
+<div
+  {...rest}
+  data-slot="item-actions"
+  class={cn("gap-2 flex items-center", className)}
+>
+  <slot />
+</div>

package/src/components/item/ItemContent.astro

@@ -1,25 +1,25 @@
----
-import { cn } from "@cl-light-ds/ui/lib/utils";
-import type { HTMLAttributes } from "astro/types";
-
-interface Props extends HTMLAttributes<"div"> {
-  class?: string;
-}
-
-const {
-  class: className = "",
-  ...rest
-} = Astro.props as Props;
----
-
-<div
-  {...rest}
-  data-slot="item-content"
-  class={cn(
-    "gap-1",
-    "flex flex-1 flex-col [&+[data-slot=item-content]]:flex-none",
-    className,
-  )}
->
-  <slot />
-</div>
+---
+import { cn } from "@cl-light-ds/ui/lib/utils";
+import type { HTMLAttributes } from "astro/types";
+
+interface Props extends HTMLAttributes<"div"> {
+  class?: string;
+}
+
+const {
+  class: className = "",
+  ...rest
+} = Astro.props as Props;
+---
+
+<div
+  {...rest}
+  data-slot="item-content"
+  class={cn(
+    "gap-1",
+    "flex flex-1 flex-col [&+[data-slot=item-content]]:flex-none",
+    className,
+  )}
+>
+  <slot />
+</div>

package/src/components/item/ItemDescription.astro

@@ -1,25 +1,25 @@
----
-import { cn } from "@cl-light-ds/ui/lib/utils";
-import type { HTMLAttributes } from "astro/types";
-
-interface Props extends HTMLAttributes<"p"> {
-  class?: string;
-}
-
-const {
-  class: className = "",
-  ...rest
-} = Astro.props as Props;
----
-
-<p
-  {...rest}
-  data-slot="item-description"
-  class={cn(
-    "text-muted-foreground text-left text-sm leading-normal",
-    "line-clamp-2 text-balance",
-    className,
-  )}
->
-  <slot />
-</p>
+---
+import { cn } from "@cl-light-ds/ui/lib/utils";
+import type { HTMLAttributes } from "astro/types";
+
+interface Props extends HTMLAttributes<"p"> {
+  class?: string;
+}
+
+const {
+  class: className = "",
+  ...rest
+} = Astro.props as Props;
+---
+
+<p
+  {...rest}
+  data-slot="item-description"
+  class={cn(
+    "text-muted-foreground text-left text-sm leading-normal",
+    "line-clamp-2 text-balance",
+    className,
+  )}
+>
+  <slot />
+</p>

package/src/components/item/ItemFooter.astro

@@ -1,24 +1,24 @@
----
-import { cn } from "@cl-light-ds/ui/lib/utils";
-import type { HTMLAttributes } from "astro/types";
-
-interface Props extends HTMLAttributes<"div"> {
-  class?: string;
-}
-
-const {
-  class: className = "",
-  ...rest
-} = Astro.props as Props;
----
-
-<div
-  {...rest}
-  data-slot="item-footer"
-  class={cn(
-    "gap-2 flex basis-full items-center justify-between",
-    className,
-  )}
->
-  <slot />
-</div>
+---
+import { cn } from "@cl-light-ds/ui/lib/utils";
+import type { HTMLAttributes } from "astro/types";
+
+interface Props extends HTMLAttributes<"div"> {
+  class?: string;
+}
+
+const {
+  class: className = "",
+  ...rest
+} = Astro.props as Props;
+---
+
+<div
+  {...rest}
+  data-slot="item-footer"
+  class={cn(
+    "gap-2 flex basis-full items-center justify-between",
+    className,
+  )}
+>
+  <slot />
+</div>

package/src/components/item/ItemGroup.astro

@@ -1,24 +1,24 @@
----
-import { cn } from "@cl-light-ds/ui/lib/utils";
-import type { HTMLAttributes, HTMLTag } from "astro/types";
-
-interface Props extends HTMLAttributes<"div"> {
-  as?: HTMLTag;
-  class?: string;
-}
-
-const {
-  as: Tag = "div",
-  class: className = "",
-  ...rest
-} = Astro.props as Props;
----
-
-<Tag
-  {...rest}
-  role="list"
-  data-slot="item-group"
-  class={cn("gap-4 has-data-[size=sm]:gap-2.5 group/item-group flex flex-col", className)}
->
-  <slot />
-</Tag>
+---
+import { cn } from "@cl-light-ds/ui/lib/utils";
+import type { HTMLAttributes, HTMLTag } from "astro/types";
+
+interface Props extends HTMLAttributes<"div"> {
+  as?: HTMLTag;
+  class?: string;
+}
+
+const {
+  as: Tag = "div",
+  class: className = "",
+  ...rest
+} = Astro.props as Props;
+---
+
+<Tag
+  {...rest}
+  role="list"
+  data-slot="item-group"
+  class={cn("gap-4 has-data-[size=sm]:gap-2.5 group/item-group flex flex-col", className)}
+>
+  <slot />
+</Tag>

package/src/components/item/ItemHeader.astro

@@ -1,24 +1,24 @@
----
-import { cn } from "@cl-light-ds/ui/lib/utils";
-import type { HTMLAttributes } from "astro/types";
-
-interface Props extends HTMLAttributes<"div"> {
-  class?: string;
-}
-
-const {
-  class: className = "",
-  ...rest
-} = Astro.props as Props;
----
-
-<div
-  {...rest}
-  data-slot="item-header"
-  class={cn(
-    "gap-2 flex basis-full items-center justify-between",
-    className,
-  )}
->
-  <slot />
-</div>
+---
+import { cn } from "@cl-light-ds/ui/lib/utils";
+import type { HTMLAttributes } from "astro/types";
+
+interface Props extends HTMLAttributes<"div"> {
+  class?: string;
+}
+
+const {
+  class: className = "",
+  ...rest
+} = Astro.props as Props;
+---
+
+<div
+  {...rest}
+  data-slot="item-header"
+  class={cn(
+    "gap-2 flex basis-full items-center justify-between",
+    className,
+  )}
+>
+  <slot />
+</div>