@boxcustodia/library 2.0.0-alpha.13 → 2.0.0-alpha.14

package/src/components/radio-group/radio-group.tsx

@@ -0,0 +1,212 @@
+import { Field as FieldBase } from "@base-ui/react/field";
+import { Radio as RadioPrimitive } from "@base-ui/react/radio";
+import { RadioGroup as RadioGroupPrimitive } from "@base-ui/react/radio-group";
+import { createContext, type ReactNode, useContext, useId } from "react";
+import { cn } from "../../lib";
+import {
+  FieldLegend,
+  FieldSet,
+  FieldValidity,
+  useFieldName,
+  useIsInsideFieldRoot,
+} from "../field/field";
+import { Label } from "../label";
+
+// ── Primitives ─────────────────────────────────────────────────────────────────
+
+export function RadioGroupRoot({
+  className,
+  ...props
+}: RadioGroupPrimitive.Props) {
+  return (
+    <RadioGroupPrimitive
+      className={cn("grid w-full gap-2", className)}
+      data-slot="radio-group"
+      {...props}
+    />
+  );
+}
+
+export function RadioRoot({ className, ...props }: RadioPrimitive.Root.Props) {
+  return (
+    <RadioPrimitive.Root
+      className={cn(
+        "peer relative inline-flex size-4.5 shrink-0 items-center justify-center rounded-full border border-input bg-background not-dark:bg-clip-padding shadow-xs/5 outline-none ring-ring transition-shadow",
+        "before:pointer-events-none before:absolute before:inset-0 before:rounded-full",
+        "not-data-disabled:not-data-checked:not-aria-invalid:before:shadow-[0_1px_--theme(--color-black/4%)]",
+        "focus-visible:ring-2 focus-visible:ring-offset-1 focus-visible:ring-offset-background",
+        "aria-invalid:border-error focus-visible:aria-invalid:border-error focus-visible:aria-invalid:ring-error",
+        "data-disabled:cursor-not-allowed data-disabled:opacity-64",
+        "sm:size-4",
+        "dark:not-data-disabled:not-data-checked:not-aria-invalid:before:shadow-[0_-1px_--theme(--color-white/6%)]",
+        "[[data-disabled],[data-checked],[aria-invalid]]:shadow-none",
+        "data-checked:border-primary data-checked:bg-primary",
+        className,
+      )}
+      data-slot="radio"
+      {...props}
+    />
+  );
+}
+
+export function RadioIndicator({
+  className,
+  children,
+  ...props
+}: RadioPrimitive.Indicator.Props) {
+  return (
+    <RadioPrimitive.Indicator
+      className={cn("flex size-full items-center justify-center", className)}
+      data-slot="radio-indicator"
+      {...props}
+    >
+      {children ?? (
+        <span className="size-2 rounded-full bg-primary-foreground" />
+      )}
+    </RadioPrimitive.Indicator>
+  );
+}
+
+// ── Group context ──────────────────────────────────────────────────────────────
+
+const RadioGroupContext = createContext<{
+  controlFirst: boolean;
+  invalid: boolean;
+}>({
+  controlFirst: true,
+  invalid: false,
+});
+
+// ── Composite: RadioGroup.Item ─────────────────────────────────────────────────
+
+export interface RadioItemProps
+  extends Omit<RadioPrimitive.Root.Props, "children"> {
+  label: ReactNode;
+}
+
+function RadioGroupItem({ className, label, id, ...props }: RadioItemProps) {
+  const { controlFirst, invalid } = useContext(RadioGroupContext);
+  const generatedId = useId();
+  const idToUse = id ?? generatedId;
+
+  return (
+    <FieldBase.Root invalid={invalid}>
+      <div
+        className={cn(
+          "flex select-none items-center gap-x-2",
+          !controlFirst && "flex-row-reverse justify-end",
+        )}
+      >
+        <RadioRoot id={idToUse} className={className} {...props}>
+          <RadioIndicator />
+        </RadioRoot>
+        <Label htmlFor={idToUse}>{label}</Label>
+      </div>
+    </FieldBase.Root>
+  );
+}
+
+// ── Composite: RadioGroup.Legend ───────────────────────────────────────────────
+
+export interface RadioGroupLegendProps {
+  children: ReactNode;
+  className?: string;
+}
+
+function RadioGroupLegend({ children, className }: RadioGroupLegendProps) {
+  return <FieldLegend className={className}>{children}</FieldLegend>;
+}
+
+// ── Composite: RadioGroup ──────────────────────────────────────────────────────
+
+export interface RadioOption {
+  value: string;
+  label: ReactNode;
+  disabled?: boolean;
+}
+
+export interface RadioGroupProps {
+  legend?: ReactNode;
+  children?: ReactNode;
+  items?: RadioOption[];
+  defaultValue?: string;
+  value?: string;
+  onValueChange?: (value: string) => void;
+  disabled?: boolean;
+  required?: boolean;
+  readOnly?: boolean;
+  controlFirst?: boolean;
+  className?: string;
+  name?: string;
+  form?: string;
+}
+
+function RadioGroupComposite({
+  legend,
+  children,
+  items,
+  defaultValue,
+  value,
+  onValueChange,
+  disabled,
+  required,
+  readOnly,
+  controlFirst = true,
+  className,
+  name: nameProp,
+  form,
+}: RadioGroupProps) {
+  const fieldName = useFieldName();
+  const isInsideField = useIsInsideFieldRoot();
+  const name = nameProp ?? fieldName;
+
+  const renderGroup = (invalid: boolean) => (
+    <RadioGroupContext.Provider value={{ controlFirst, invalid }}>
+      <RadioGroupPrimitive
+        defaultValue={defaultValue}
+        value={value}
+        onValueChange={onValueChange}
+        disabled={disabled}
+        required={required}
+        readOnly={readOnly}
+        name={name}
+        form={form}
+      >
+        <FieldSet className={className}>
+          {legend && <RadioGroupLegend>{legend}</RadioGroupLegend>}
+          <div className="flex flex-col gap-2">
+            {items
+              ? items.map((item) => (
+                  <RadioGroupItem
+                    key={item.value}
+                    value={item.value}
+                    label={item.label}
+                    disabled={item.disabled}
+                  />
+                ))
+              : children}
+          </div>
+        </FieldSet>
+      </RadioGroupPrimitive>
+    </RadioGroupContext.Provider>
+  );
+
+  if (!isInsideField) return renderGroup(false);
+
+  return (
+    <FieldValidity>
+      {({ validity }) => renderGroup(validity.valid === false)}
+    </FieldValidity>
+  );
+}
+
+// ── Compound export ────────────────────────────────────────────────────────────
+
+export const RadioGroup = Object.assign(RadioGroupComposite, {
+  Item: RadioGroupItem,
+  Legend: RadioGroupLegend,
+});
+
+// ── Primitive escape hatch ─────────────────────────────────────────────────────
+
+export { RadioGroupPrimitive, RadioPrimitive };

package/src/components/scroll-area/scroll-area.stories.tsx

@@ -31,6 +31,7 @@ const meta: Meta<typeof ScrollArea> = {
   argTypes: {
     children: { control: false },
   },
+  tags: ["new"],
 };
 
 export default meta;

package/src/components/select/select.stories.tsx

@@ -32,14 +32,14 @@ const animals: Animal[] = [
 ];
 
 /**
- * Single-selection dropdown built on Base UI. Items shaped as `{ label, value }`
- * or plain strings/numbers work with no extra props. Provide `getLabel`/`getValue`
- * for custom object shapes, or `renderItem` to control the content inside each
- * option — the checkmark indicator is always appended on the right.
+ * Single-selection dropdown built on Base UI. Items shaped as `{ id, name }`,
+ * `{ label, value }`, or plain strings/numbers work with no extra props. Provide
+ * `getLabel` / `getId` for custom object shapes, or `renderItem` to control the
+ * content inside each option — the checkmark indicator is always appended on the right.
  *
- * Exposes `onChange` instead of Base UI's `onValueChange`. `onChange` receives
- * the full item object (or `null`). For controlled usage, pass `value` + `onChange`
- * together. Use `SelectRoot` + primitives for full structural control.
+ * Exposes `onValueChange` that receives the full item object (or `null`).
+ * For controlled usage, pass `value` + `onValueChange` together.
+ * Use `SelectRoot` + primitives for full structural control.
  */
 const meta: Meta<typeof Select> = {
   title: "Components/Select",
@@ -53,13 +53,12 @@ const meta: Meta<typeof Select> = {
     ),
   ],
   argTypes: {
-    onChange: { control: false },
+    onValueChange: { control: false },
     getLabel: { control: false },
-    getValue: { control: false },
+    getId: { control: false },
+    getDisabled: { control: false },
     renderItem: { control: false },
-    triggerProps: { control: false },
-    popupProps: { control: false },
-    itemProps: { control: false },
+    classNames: { control: false },
   },
   args: {
     items: animals,
@@ -72,13 +71,113 @@ type Story = StoryObj<typeof Select>;
 
 export const Default: Story = {};
 
+/**
+ * `className` styles the trigger. `classNames` exposes the `popup` and
+ * `item` slots.
+ */
+export const WithClassNames: Story = {
+  args: {
+    classNames: {
+      popup: "min-w-56",
+      item: "font-mono",
+    },
+  },
+};
+
 export const Disabled: Story = {
   args: { disabled: true },
 };
 
 /**
- * `getLabel` and `getValue` accept functions so they work with any object
- * shape, not just `{ label, value }`.
+ * `alignItemWithTrigger` controla cómo posiciona Base UI el popup respecto al trigger.
+ *
+ * - **Default (`false`)**: el popup aparece debajo del trigger como un combo común.
+ *   Es el comportamiento esperado cuando hay muchos items o cuando el popup no debería
+ *   crecer hasta llenar el viewport intentando alinear el item seleccionado con el trigger.
+ * - **`true`**: Base UI intenta alinear el item seleccionado con el trigger y expande
+ *   el popup hacia arriba y abajo. Útil para listas cortas con un valor preseleccionado,
+ *   estilo `<select>` nativo de macOS.
+ *
+ * Es un cambio estructural — usá `SelectRoot` + `SelectPopup` directamente
+ * para activarlo:
+ *
+ * ```tsx
+ * <SelectRoot>
+ *   <SelectTrigger><SelectValue /></SelectTrigger>
+ *   <SelectPopup alignItemWithTrigger>…</SelectPopup>
+ * </SelectRoot>
+ * ```
+ */
+export const AlignItemWithTrigger: Story = {
+  render: () => {
+    const years = Array.from({ length: 40 }, (_, i) => {
+      const year = 1990 + i;
+      return { label: String(year), value: String(year) };
+    });
+    const preselected = years[20];
+
+    return (
+      <div className="flex flex-col gap-6">
+        <div className="flex flex-col gap-1">
+          <span className="text-muted-foreground text-xs">
+            Default (alignItemWithTrigger=false)
+          </span>
+          <Select items={years} defaultValue={preselected} />
+        </div>
+        <div className="flex flex-col gap-1">
+          <span className="text-muted-foreground text-xs">
+            alignItemWithTrigger=true
+          </span>
+          <SelectRoot defaultValue={preselected.value}>
+            <SelectTrigger>
+              <SelectValue />
+            </SelectTrigger>
+            <SelectPopup alignItemWithTrigger>
+              {years.map((y) => (
+                <SelectItem key={y.value} value={y.value}>
+                  {y.label}
+                </SelectItem>
+              ))}
+            </SelectPopup>
+          </SelectRoot>
+        </div>
+      </div>
+    );
+  },
+};
+
+/**
+ * `getDisabled` receives a predicate `(item) => boolean` to disable individual
+ * options. Items with a `disabled: true` property are disabled automatically
+ * without passing this prop.
+ *
+ * A disabled item is skipped during keyboard navigation and cannot be selected,
+ * but it remains visible in the list at reduced opacity.
+ */
+export const DisabledItem: Story = {
+  render: () => {
+    const items = [
+      { label: "Cat", value: "cat" },
+      { label: "Dog", value: "dog" },
+      { label: "Bird", value: "bird" },
+      { label: "Rabbit", value: "rabbit" },
+      { label: "Fish", value: "fish" },
+    ];
+
+    return (
+      <Select
+        items={items}
+        getDisabled={(item) => item.value === "bird" || item.value === "fish"}
+        placeholder="Select an animal"
+      />
+    );
+  },
+};
+
+/**
+ * `getLabel` and `getId` accept functions so they work with any object shape.
+ * For common shapes (`{ id, name }`, `{ label, value }`, primitives) the
+ * defaults resolve everything without passing either function.
  */
 export const CustomObject: Story = {
   render: () => {
@@ -92,7 +191,7 @@ export const CustomObject: Story = {
       <Select
         items={items}
         getLabel={(a) => a.name}
-        getValue={(a) => a.key}
+        getId={(a) => a.key}
         placeholder="Select an animal"
       />
     );
@@ -102,7 +201,7 @@ export const CustomObject: Story = {
 /**
  * `multiple` enables multi-selection. The trigger shows selected labels as a
  * comma-separated list with automatic truncation. Use `value: TItem[]` and
- * `onChange: (value: TItem[]) => void` for controlled usage — the discriminated
+ * `onValueChange: (value: TItem[]) => void` for controlled usage — the discriminated
  * union ensures type safety between single and multiple modes.
  */
 export const Multiple: Story = {
@@ -127,7 +226,7 @@ export const CustomRender: Story = {
       <Select
         items={items}
         getLabel={(a) => a.name}
-        getValue={(a) => a.key}
+        getId={(a) => a.key}
         renderItem={(a) => (
           <span className="flex items-center gap-2">
             <span>{a.emoji}</span>
@@ -141,7 +240,7 @@ export const CustomRender: Story = {
 };
 
 /**
- * `onChange` receives the full item object (or `null`).
+ * `onValueChange` receives the full item object (or `null`).
  * `value` accepts the item object directly — no string conversion needed.
  */
 export const Controlled: Story = {
@@ -152,7 +251,7 @@ export const Controlled: Story = {
         <Select
           {...args}
           value={value ?? null}
-          onChange={(item) => updateArgs({ value: item })}
+          onValueChange={(item) => updateArgs({ value: item })}
         />
         <p className="text-sm text-muted-foreground">
           Selected: {value ? (value as Animal).label : "none"}

package/src/components/select/select.tsx

@@ -30,12 +30,9 @@ export function SelectRoot<
   Value = string,
   Multiple extends boolean | undefined = false,
 >({
-  onChange,
   ...props
-}: Omit<SelectPrimitive.Root.Props<Value, Multiple>, "onValueChange"> & {
-  onChange?: SelectPrimitive.Root.Props<Value, Multiple>["onValueChange"];
-}): React.ReactElement {
-  return <SelectPrimitive.Root onValueChange={onChange} {...props} />;
+}: SelectPrimitive.Root.Props<Value, Multiple>): React.ReactElement {
+  return <SelectPrimitive.Root {...props} />;
 }
 
 export function SelectTrigger({
@@ -117,7 +114,7 @@ export function SelectPopup({
   sideOffset = 4,
   align = "start",
   alignOffset = 0,
-  alignItemWithTrigger = true,
+  alignItemWithTrigger = false,
   anchor,
   portalProps,
   ...props
@@ -156,7 +153,7 @@ export function SelectPopup({
           <div className="relative h-full min-w-(--anchor-width) rounded-lg border bg-popover not-dark:bg-clip-padding shadow-lg/5 before:pointer-events-none before:absolute before:inset-0 before:rounded-[calc(var(--radius-lg)-1px)] before:shadow-[0_1px_--theme(--color-black/4%)] dark:before:shadow-[0_-1px_--theme(--color-white/6%)]">
             <SelectPrimitive.List
               className={cn(
-                "max-h-(--available-height) overflow-y-auto p-1",
+                "max-h-[min(24rem,var(--available-height))] overflow-y-auto p-1",
                 className,
               )}
               data-slot="select-list"
@@ -265,41 +262,53 @@ export function SelectLabel({
 function defaultGetLabel(item: unknown): string {
   if (item == null) return "";
   if (typeof item === "string" || typeof item === "number") return String(item);
-  if (typeof item === "object" && "label" in item)
-    return String((item as Record<string, unknown>).label);
+  if (typeof item === "object") {
+    const record = item as Record<string, unknown>;
+    if ("label" in record) return String(record.label);
+    if ("name" in record) return String(record.name);
+    if ("title" in record) return String(record.title);
+  }
   return String(item);
 }
 
-function defaultGetValue(item: unknown): string {
+function defaultGetId(item: unknown): string {
   if (item == null) return "";
   if (typeof item === "string" || typeof item === "number") return String(item);
-  if (typeof item === "object" && "value" in item)
-    return String((item as Record<string, unknown>).value);
+  if (typeof item === "object") {
+    const record = item as Record<string, unknown>;
+    if ("id" in record) return String(record.id);
+    if ("value" in record) return String(record.value);
+  }
   return String(item);
 }
 
-type SelectRootPropsAlias<V = string> = Omit<
-  SelectPrimitive.Root.Props<V, false>,
-  "onValueChange"
-> & {
-  onChange?: SelectPrimitive.Root.Props<V, false>["onValueChange"];
-};
+function defaultGetDisabled(item: unknown): boolean {
+  if (item != null && typeof item === "object" && "disabled" in item)
+    return Boolean((item as Record<string, unknown>).disabled);
+  return false;
+}
 
 type SelectBaseProps<TItem = unknown> = Omit<
-  SelectRootPropsAlias<string>,
-  "children" | "onChange" | "value" | "defaultValue" | "items" | "multiple"
+  SelectPrimitive.Root.Props<string, false>,
+  "children" | "onValueChange" | "value" | "defaultValue" | "items" | "multiple"
 > & {
   items: readonly TItem[];
+  /** Returns the display text for an item. Used for the trigger value and ARIA. Defaults to `item.label`, `item.name`, `item.title`, or the stringified primitive. */
   getLabel?: (item: TItem) => string;
-  getValue?: (item: TItem) => string;
+  /** Returns a stable string identifier for an item. Used as the React key and the underlying option value. Defaults to `item.id`, `item.value`, or the stringified primitive. */
+  getId?: (item: TItem) => string;
+  /** Returns whether an item should be disabled. Defaults to `item.disabled === true`. */
+  getDisabled?: (item: TItem) => boolean;
   renderItem?: (item: TItem) => React.ReactNode;
   placeholder?: string;
-  triggerProps?: React.ComponentProps<typeof SelectTrigger>;
-  popupProps?: React.ComponentProps<typeof SelectPopup>;
-  popupClassName?: string;
-  itemProps?: SelectPrimitive.Item.Props;
-  itemClassName?: string;
   className?: string;
+  /** Styles applied to each internal slot. */
+  classNames?: {
+    /** Popup panel containing the item list. */
+    popup?: string;
+    /** Individual item row. */
+    item?: string;
+  };
 };
 
 export type SelectProps<TItem = unknown> =
@@ -307,25 +316,26 @@ export type SelectProps<TItem = unknown> =
       multiple?: false;
       value?: TItem | null;
       defaultValue?: TItem | null;
-      onChange?: (value: TItem | null) => void;
+      onValueChange?: (value: TItem | null) => void;
     })
   | (SelectBaseProps<TItem> & {
       multiple: true;
       value?: TItem[];
       defaultValue?: TItem[];
-      onChange?: (value: TItem[]) => void;
+      onValueChange?: (value: TItem[]) => void;
     });
 
 /**
- * Composite select for single and multiple selection. Items shaped as
- * `{ label, value }` or plain strings/numbers work with no extra props.
- * For other shapes, provide `getLabel` and/or `getValue`.
+ * Composite select for single and multiple selection.
+ *
+ * Items shaped as `{ id, name }`, `{ label, value }`, or plain strings/numbers
+ * work with no extra props. For other shapes, provide `getLabel` and/or `getId`.
  *
  * `renderItem` customizes the content **inside** each `SelectItem` (the
  * checkmark indicator is always rendered by the item wrapper).
  *
  * Use `SelectRoot` + primitives directly when you need full structural
- * control beyond what escape-hatch props offer.
+ * control beyond what `className` + `classNames` slots offer.
  */
 export function Select<TItem = unknown>(
   allProps: SelectProps<TItem>,
@@ -333,88 +343,83 @@ export function Select<TItem = unknown>(
   const {
     items,
     getLabel: getLabelProp,
-    getValue: getValueProp,
+    getId: getIdProp,
+    getDisabled: getDisabledProp,
     renderItem,
     placeholder,
-    onChange,
+    onValueChange,
     value,
     defaultValue,
     multiple,
-    triggerProps,
-    popupProps,
-    itemProps,
-    itemClassName,
     className,
-    popupClassName,
+    classNames,
     ...rest
   } = allProps as SelectBaseProps<TItem> & {
     multiple?: boolean;
-    onChange?: (value: any) => void;
+    onValueChange?: (value: any) => void;
     value?: any;
     defaultValue?: any;
   };
 
   const getLabel: (item: TItem) => string = getLabelProp ?? defaultGetLabel;
-  const getValue: (item: TItem) => string = getValueProp ?? defaultGetValue;
+  const getId: (item: TItem) => string = getIdProp ?? defaultGetId;
+  const getDisabled: (item: TItem) => boolean =
+    getDisabledProp ?? defaultGetDisabled;
 
   const stringValue = multiple
-    ? (value as TItem[] | undefined)?.map(getValue)
+    ? (value as TItem[] | undefined)?.map(getId)
     : value != null
-      ? getValue(value as TItem)
+      ? getId(value as TItem)
       : undefined;
 
   const stringDefaultValue = multiple
-    ? (defaultValue as TItem[] | undefined)?.map(getValue)
+    ? (defaultValue as TItem[] | undefined)?.map(getId)
     : defaultValue != null
-      ? getValue(defaultValue as TItem)
+      ? getId(defaultValue as TItem)
       : undefined;
 
   const handleChange = (stringVal: string | string[] | null) => {
     if (multiple) {
       const vals = (stringVal as string[]) ?? [];
       const found = vals
-        .map((sv) => items.find((i) => getValue(i) === sv) ?? null)
+        .map((sv) => items.find((i) => getId(i) === sv) ?? null)
         .filter(Boolean) as TItem[];
-      onChange?.(found);
+      onValueChange?.(found);
     } else {
       if (stringVal == null) {
-        onChange?.(null);
+        onValueChange?.(null);
         return;
       }
       const item =
-        items.find((i) => getValue(i) === (stringVal as string)) ?? null;
-      onChange?.(item);
+        items.find((i) => getId(i) === (stringVal as string)) ?? null;
+      onValueChange?.(item);
     }
   };
 
   const itemToStringLabel = (stringVal: string) => {
-    const item = items.find((i) => getValue(i) === stringVal);
+    const item = items.find((i) => getId(i) === stringVal);
     return item ? getLabel(item) : stringVal;
   };
 
   return (
     <SelectRoot
       itemToStringLabel={itemToStringLabel}
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
       multiple={multiple as any}
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
       value={stringValue as any}
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
       defaultValue={stringDefaultValue as any}
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      onChange={handleChange as any}
+      onValueChange={handleChange as any}
       {...(rest as any)}
     >
-      <SelectTrigger className={className} {...triggerProps}>
+      <SelectTrigger className={className}>
         <SelectValue placeholder={placeholder} />
       </SelectTrigger>
-      <SelectPopup className={popupClassName} {...popupProps}>
+      <SelectPopup className={classNames?.popup}>
         {items.map((item) => (
           <SelectItem
-            key={getValue(item)}
-            value={getValue(item)}
-            className={itemClassName}
-            {...itemProps}
+            key={getId(item)}
+            value={getId(item)}
+            disabled={getDisabled(item)}
+            className={classNames?.item}
           >
             {renderItem ? renderItem(item) : getLabel(item)}
           </SelectItem>

package/src/components/skeleton/skeleton.stories.tsx

@@ -12,6 +12,7 @@ const meta: Meta<typeof Skeleton> = {
   args: {
     className: "h-4 w-[200px]",
   },
+  parameters: { layout: "centered" },
 };
 
 export default meta;