@central-ui/react 0.0.0-stage → 0.1.1

package/dist/utils/virtualization/useVirtualizedCombobox.js

@@ -0,0 +1,174 @@
+import { Combobox as BaseCombobox } from '@base-ui/react/combobox';
+import { useCallback, useLayoutEffect, useRef, useState } from 'react';
+import { useVirtualizer } from '@tanstack/react-virtual';
+/**
+ * Virtualize a large Combobox while keeping native search and keyboard behavior.
+ * Call this hook in your component, outside Root. Spread each returned props object
+ * on its matching element, and keep ComboboxFilteredItemsSync mounted inside Popup
+ * so native filtering supplies the complete results. Keep rootProps.onItemHighlighted
+ * connected; it scrolls keyboard highlights into view. Merge it if adding your own callback.
+ *
+ * Filtered groups are flattened into one list: this hook does not virtualize separate
+ * group headings. Use one shared heading, as below, or omit GroupLabel for a flat list
+ * and adjust paddingStart. Preserve the returned refs and layout styles when customizing.
+ * Render only rows, but give Group all filteredItems and each Item its returned index.
+ * The mapped rows already preserve your custom item fields; no manual annotation is needed.
+ *
+ * @example Complete virtualized Combobox
+ * import {
+ *   Combobox,
+ *   ComboboxFilteredItemsSync,
+ *   useVirtualizedCombobox,
+ * } from '@central-ui/react'
+ *
+ * // Replace this sample with your larger dataset; keep the source stable between renders.
+ * const cityGroups = [{
+ *   label: 'Cities',
+ *   items: [
+ *     { value: 'ma-rabat', label: 'Rabat', country: 'Morocco', population: 580000 },
+ *     { value: 'ma-casablanca', label: 'Casablanca', country: 'Morocco', population: 3359818 },
+ *     { value: 'fr-paris', label: 'Paris', country: 'France', population: 2102650 },
+ *   ],
+ * }]
+ *
+ * function CityCombobox() {
+ *   const virtual = useVirtualizedCombobox({
+ *     items: cityGroups, // rootProps supplies these complete groups to Root.
+ *     estimateSize: 34, // Match the row height plus spacing in your layout.
+ *     paddingStart: 32, // Match the heading and leading space; adjust if styled differently.
+ *     paddingEnd: 4, // Match the trailing group padding.
+ *   })
+ *
+ *   return (
+ *     <Combobox.Root {...virtual.rootProps}>
+ *       <Combobox.Container>
+ *         <Combobox.Label>City</Combobox.Label>
+ *         <Combobox.InputGroup>
+ *           <Combobox.Input placeholder="Search cities" />
+ *           <Combobox.Addon>
+ *             <Combobox.AddonOpenButton aria-label="Show cities">
+ *               <Combobox.AddonOpenButtonIcon />
+ *             </Combobox.AddonOpenButton>
+ *             <Combobox.AddonClearButton aria-label="Clear city">
+ *               <Combobox.AddonClearButtonIcon />
+ *             </Combobox.AddonClearButton>
+ *           </Combobox.Addon>
+ *         </Combobox.InputGroup>
+ *         <Combobox.Popup>
+ *           <ComboboxFilteredItemsSync {...virtual.filteredItemsSyncProps} />
+ *           <Combobox.Empty // Keep mounted; native filtering controls visibility.
+ *           >
+ *             <Combobox.EmptyText>No cities found.</Combobox.EmptyText>
+ *           </Combobox.Empty>
+ *           <Combobox.ScrollArea {...virtual.scrollAreaProps}>
+ *             <Combobox.GroupsList>
+ *               {virtual.filteredItems.length > 0 && (
+ *                 <Combobox.Group items={virtual.filteredItems}>
+ *                   <Combobox.GroupLabel>Cities</Combobox.GroupLabel>
+ *                   <Combobox.ItemsList {...virtual.itemsListProps}>
+ *                     {virtual.rows.map((row) => (
+ *                       <Combobox.Item
+ *                         key={row.key}
+ *                         value={row.item}
+ *                         index={row.index} // Preserve the index in the full filtered list.
+ *                         {...row.itemProps}
+ *                       >
+ *                         <Combobox.ItemText>{row.item.label}</Combobox.ItemText>
+ *                         <Combobox.ItemIndicator />
+ *                       </Combobox.Item>
+ *                     ))}
+ *                   </Combobox.ItemsList>
+ *                 </Combobox.Group>
+ *               )}
+ *             </Combobox.GroupsList>
+ *           </Combobox.ScrollArea>
+ *         </Combobox.Popup>
+ *       </Combobox.Container>
+ *     </Combobox.Root>
+ *   )
+ * }
+ */
+export function useVirtualizedCombobox({ items: source, estimateSize = 34, overscan = 5, paddingStart = 0, paddingEnd = 0, maxHeight = 320, availableHeight = 'var(--available-height)', }) {
+    const [filteredItems, setFilteredItems] = useState([]);
+    const scrollRef = useRef(null);
+    const virtualizer = useVirtualizer({
+        count: filteredItems.length,
+        getScrollElement: () => scrollRef.current,
+        estimateSize: (index) => typeof estimateSize === 'function'
+            ? estimateSize(filteredItems[index], index)
+            : estimateSize,
+        getItemKey: (index) => filteredItems[index].value,
+        overscan,
+        paddingStart,
+        paddingEnd,
+    });
+    // Filtering or sorting supplies a new array; scrolling alone must not reset it.
+    useLayoutEffect(() => {
+        virtualizer.scrollToOffset(0);
+    }, [filteredItems, virtualizer]);
+    const totalSize = virtualizer.getTotalSize();
+    const virtualRows = virtualizer.getVirtualItems();
+    const scrollAreaProps = {
+        ref: scrollRef,
+        style: {
+            height: Math.min(totalSize, maxHeight),
+            maxHeight: availableHeight,
+        },
+    };
+    // Exclude the space already occupied by the caller's heading and padding.
+    const itemsListProps = {
+        style: {
+            position: 'relative',
+            height: totalSize - paddingStart - paddingEnd,
+            flexShrink: 0,
+        },
+    };
+    const rows = virtualRows.map((row) => ({
+        key: row.key,
+        index: row.index,
+        item: filteredItems[row.index],
+        start: row.start,
+        size: row.size,
+        itemProps: {
+            style: {
+                position: 'absolute',
+                top: 0,
+                left: 0,
+                width: '100%',
+                transform: `translateY(${row.start - paddingStart}px)`,
+            },
+            'aria-setsize': filteredItems.length,
+            'aria-posinset': row.index + 1,
+        },
+    }));
+    const scrollToIndex = useCallback((index, options) => virtualizer.scrollToIndex(index, { align: 'auto', ...options }), [virtualizer]);
+    const onItemHighlighted = useCallback((item, details) => {
+        if (!item || details.reason === 'pointer' || details.index < 0)
+            return;
+        queueMicrotask(() => scrollToIndex(details.index));
+    }, [scrollToIndex]);
+    const onFilteredItemsChange = useCallback((next) => setFilteredItems(next), []);
+    return {
+        rootProps: { items: source, virtualized: true, onItemHighlighted },
+        filteredItemsSyncProps: { onChange: onFilteredItemsChange },
+        filteredItems,
+        scrollAreaProps,
+        itemsListProps,
+        rows,
+        scrollToIndex,
+        virtualizer,
+    };
+}
+/**
+ * Renders nothing. Mount inside Root (normally inside Popup) to mirror the
+ * complete native search results into the external virtualization hook.
+ * The callback infers the item type, including extra fields, without a cast.
+ */
+export function FilteredItemsSync({ onChange, }) {
+    const groups = BaseCombobox.useFilteredItems();
+    useLayoutEffect(() => {
+        onChange(groups.flatMap((group) => group.items));
+    }, [groups, onChange]);
+    return null;
+}
+//# sourceMappingURL=useVirtualizedCombobox.js.map

package/dist/utils/virtualization/useVirtualizedCombobox.js.map

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

package/dist/utils/virtualization/useVirtualizedTable.d.ts

@@ -0,0 +1,169 @@
+import type { CSSProperties } from 'react';
+export interface UseVirtualizedTableOptions<TItem> {
+    /**
+     * Pass the rows in their current display order after filtering or sorting.
+     * Keep this array stable between those changes: a new array scrolls back to the top.
+     * @example items: orders
+     */
+    items: readonly TItem[];
+    /**
+     * Return a unique database ID or another stable key so rows keep their identity
+     * when sorted or filtered. Avoid the array index when row order can change.
+     * @example getItemKey: (order) => order.id
+     */
+    getItemKey: (item: TItem, index: number) => string | number;
+    /**
+     * Match the rendered row height in pixels, including any spacing between rows.
+     * Use a callback when rows have known different heights. This hook does not
+     * automatically measure rendered rows; inaccurate sizes can leave gaps or overlaps.
+     * @example estimateSize: 34
+     * @example estimateSize: (order) => order.hasDetails ? 56 : 34
+     * @default 34
+     */
+    estimateSize?: number | ((item: TItem, index: number) => number);
+    /**
+     * Mount extra rows above and below the visible area to reduce blanks during fast
+     * scrolling. Increase this if needed, at the cost of rendering more rows.
+     * @example overscan: 8
+     * @default 5
+     */
+    overscan?: number;
+    /**
+     * Reserve leading scroll space before the first data row. The returned before
+     * spacer includes it; do not add that space a second time in your markup.
+     * The table header is outside Body, so do not include its height here.
+     * @example paddingStart: 16
+     * @default 0
+     */
+    paddingStart?: number;
+    /**
+     * Reserve trailing scroll space after the last data row. The returned after
+     * spacer includes it; do not add that space a second time in your markup.
+     * @example paddingEnd: 16
+     * @default 0
+     */
+    paddingEnd?: number;
+    /**
+     * Cap the scrolling viewport height while allowing short lists to shrink.
+     * The header stays outside this viewport and does not count toward this cap.
+     * @example maxHeight: 480
+     * @default 320
+     */
+    maxHeight?: number;
+    /**
+     * Apply an additional CSS max-height to the scrolling viewport.
+     * Use this when the surrounding layout leaves less space than maxHeight.
+     * It constrains Body only; allow separately for the header height.
+     * @example availableHeight: 'calc(100dvh - 160px)'
+     * @default maxHeight
+     */
+    availableHeight?: CSSProperties['maxHeight'];
+}
+/**
+ * Virtualize data rows while keeping table markup and columns under your control.
+ * Call the hook in your component. Spread bodyProps on the scrolling Table.Body and
+ * rowProps on each visible Table.Row. Render both spacer rows to preserve the scroll
+ * height of unmounted rows. The header is outside Body; keep its column widths aligned
+ * with the body. Do not make Table.ScrollArea a second vertical scrolling viewport.
+ *
+ * This example follows the demo's block table/grid row layout, with explicit table
+ * roles and row indices so assistive technology knows each row's position in the full
+ * collection. Keep the same grid columns for the header and body, preserve bodyProps.ref
+ * and styles, and account for the header with aria-rowcount and aria-rowindex.
+ *
+ * @example Complete virtualized table
+ * import { Table, useVirtualizedTable } from '@central-ui/react'
+ *
+ * // Stable sample records; sorting/filtering should intentionally replace this array.
+ * const orders = Array.from({ length: 5000 }, (_, index) => ({
+ *   id: 'order-' + (10000 + index),
+ *   number: '#' + (10000 + index),
+ *   customer: index % 2 === 0 ? 'Alex Morgan' : 'Sam Lee',
+ * }))
+ *
+ * function OrdersTable() {
+ *   const virtual = useVirtualizedTable({
+ *     items: orders,
+ *     getItemKey: (order) => order.id, // Preserve identity after sorting/filtering.
+ *     estimateSize: 40, // Sets the rendered data row height through rowProps.
+ *     maxHeight: 480, // Body scrolls; the header stays outside this height.
+ *   })
+ *
+ *   return (
+ *     <Table.Root>
+ *       <Table.Surface>
+ *         <Table.Table className="block w-full" role="table"
+ *           aria-label="Orders" aria-rowcount={orders.length + 1}>
+ *           <Table.Head role="rowgroup"
+ *             className="static block overflow-hidden [scrollbar-gutter:stable]">
+ *             <Table.Row role="row" aria-rowindex={1}
+ *               className="grid grid-cols-2" style={{ height: 40 }}>
+ *               <Table.HeadCell role="columnheader" className="flex items-center">
+ *                 Order
+ *               </Table.HeadCell>
+ *               <Table.HeadCell role="columnheader" className="flex items-center">
+ *                 Customer
+ *               </Table.HeadCell>
+ *             </Table.Row>
+ *           </Table.Head>
+ *           <Table.Body {...virtual.bodyProps} role="rowgroup"
+ *             className="block overflow-y-auto [scrollbar-gutter:stable]">
+ *             {virtual.spacers.before > 0 && (
+ *               <tr aria-hidden="true" className="block">
+ *                 <td colSpan={2} className="block"
+ *                   style={{ height: virtual.spacers.before, padding: 0, border: 0 }} />
+ *               </tr>
+ *             )}
+ *             {virtual.rows.map((row) => (
+ *               <Table.Row key={row.key} {...row.rowProps} role="row"
+ *                 className="grid grid-cols-2" aria-rowindex={row.index + 2}>
+ *                 <Table.Cell role="cell" className="flex h-full items-center">
+ *                   {row.item.number}
+ *                 </Table.Cell>
+ *                 <Table.Cell role="cell" className="flex h-full items-center">
+ *                   {row.item.customer}
+ *                 </Table.Cell>
+ *               </Table.Row>
+ *             ))}
+ *             {virtual.spacers.after > 0 && (
+ *               <tr aria-hidden="true" className="block">
+ *                 <td colSpan={2} className="block"
+ *                   style={{ height: virtual.spacers.after, padding: 0, border: 0 }} />
+ *               </tr>
+ *             )}
+ *           </Table.Body>
+ *         </Table.Table>
+ *       </Table.Surface>
+ *     </Table.Root>
+ *   )
+ * }
+ */
+export declare function useVirtualizedTable<TItem>({ items, getItemKey, estimateSize, overscan, paddingStart, paddingEnd, maxHeight, availableHeight, }: UseVirtualizedTableOptions<TItem>): {
+    bodyProps: {
+        ref: import("react").RefObject<HTMLTableSectionElement | null>;
+        style: {
+            height: number;
+            maxHeight: import("csstype").Property.MaxHeight<string | number>;
+            overflowY: "auto";
+        };
+    };
+    rows: {
+        key: string | number | bigint;
+        index: number;
+        item: TItem;
+        start: number;
+        size: number;
+        rowProps: {
+            style: {
+                height: number;
+            };
+        };
+    }[];
+    spacers: {
+        before: number;
+        after: number;
+    };
+    scrollToIndex: (index: number, options?: Parameters<(index: number, { align: initialAlign, behavior, }?: import("@tanstack/virtual-core").ScrollToOptions) => void>[1]) => void;
+    virtualizer: import("@tanstack/react-virtual").ReactVirtualizer<HTMLTableSectionElement, HTMLTableRowElement>;
+};
+//# sourceMappingURL=useVirtualizedTable.d.ts.map

package/dist/utils/virtualization/useVirtualizedTable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useVirtualizedTable.d.ts","sourceRoot":"","sources":["../../../src/utils/virtualization/useVirtualizedTable.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,OAAO,CAAA;AAG1C,MAAM,WAAW,0BAA0B,CAAC,KAAK;IAC/C;;;;OAIG;IACH,KAAK,EAAE,SAAS,KAAK,EAAE,CAAA;IACvB;;;;OAIG;IACH,UAAU,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,KAAK,MAAM,GAAG,MAAM,CAAA;IAC3D;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC,CAAA;IAChE;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,aAAa,CAAC,WAAW,CAAC,CAAA;CAC7C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8EG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,EACzC,KAAK,EACL,UAAU,EACV,YAAiB,EACjB,QAAY,EACZ,YAAgB,EAChB,UAAc,EACd,SAAe,EACf,eAA2B,GAC5B,EAAE,0BAA0B,CAAC,KAAK,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;2BAmDvB,MAAM,YACH,UAAU,gHAAkC,CAAC,CAAC,CAAC;;EAM9D"}

package/dist/utils/virtualization/useVirtualizedTable.js

@@ -0,0 +1,127 @@
+import { useCallback, useLayoutEffect, useRef } from 'react';
+import { useVirtualizer } from '@tanstack/react-virtual';
+/**
+ * Virtualize data rows while keeping table markup and columns under your control.
+ * Call the hook in your component. Spread bodyProps on the scrolling Table.Body and
+ * rowProps on each visible Table.Row. Render both spacer rows to preserve the scroll
+ * height of unmounted rows. The header is outside Body; keep its column widths aligned
+ * with the body. Do not make Table.ScrollArea a second vertical scrolling viewport.
+ *
+ * This example follows the demo's block table/grid row layout, with explicit table
+ * roles and row indices so assistive technology knows each row's position in the full
+ * collection. Keep the same grid columns for the header and body, preserve bodyProps.ref
+ * and styles, and account for the header with aria-rowcount and aria-rowindex.
+ *
+ * @example Complete virtualized table
+ * import { Table, useVirtualizedTable } from '@central-ui/react'
+ *
+ * // Stable sample records; sorting/filtering should intentionally replace this array.
+ * const orders = Array.from({ length: 5000 }, (_, index) => ({
+ *   id: 'order-' + (10000 + index),
+ *   number: '#' + (10000 + index),
+ *   customer: index % 2 === 0 ? 'Alex Morgan' : 'Sam Lee',
+ * }))
+ *
+ * function OrdersTable() {
+ *   const virtual = useVirtualizedTable({
+ *     items: orders,
+ *     getItemKey: (order) => order.id, // Preserve identity after sorting/filtering.
+ *     estimateSize: 40, // Sets the rendered data row height through rowProps.
+ *     maxHeight: 480, // Body scrolls; the header stays outside this height.
+ *   })
+ *
+ *   return (
+ *     <Table.Root>
+ *       <Table.Surface>
+ *         <Table.Table className="block w-full" role="table"
+ *           aria-label="Orders" aria-rowcount={orders.length + 1}>
+ *           <Table.Head role="rowgroup"
+ *             className="static block overflow-hidden [scrollbar-gutter:stable]">
+ *             <Table.Row role="row" aria-rowindex={1}
+ *               className="grid grid-cols-2" style={{ height: 40 }}>
+ *               <Table.HeadCell role="columnheader" className="flex items-center">
+ *                 Order
+ *               </Table.HeadCell>
+ *               <Table.HeadCell role="columnheader" className="flex items-center">
+ *                 Customer
+ *               </Table.HeadCell>
+ *             </Table.Row>
+ *           </Table.Head>
+ *           <Table.Body {...virtual.bodyProps} role="rowgroup"
+ *             className="block overflow-y-auto [scrollbar-gutter:stable]">
+ *             {virtual.spacers.before > 0 && (
+ *               <tr aria-hidden="true" className="block">
+ *                 <td colSpan={2} className="block"
+ *                   style={{ height: virtual.spacers.before, padding: 0, border: 0 }} />
+ *               </tr>
+ *             )}
+ *             {virtual.rows.map((row) => (
+ *               <Table.Row key={row.key} {...row.rowProps} role="row"
+ *                 className="grid grid-cols-2" aria-rowindex={row.index + 2}>
+ *                 <Table.Cell role="cell" className="flex h-full items-center">
+ *                   {row.item.number}
+ *                 </Table.Cell>
+ *                 <Table.Cell role="cell" className="flex h-full items-center">
+ *                   {row.item.customer}
+ *                 </Table.Cell>
+ *               </Table.Row>
+ *             ))}
+ *             {virtual.spacers.after > 0 && (
+ *               <tr aria-hidden="true" className="block">
+ *                 <td colSpan={2} className="block"
+ *                   style={{ height: virtual.spacers.after, padding: 0, border: 0 }} />
+ *               </tr>
+ *             )}
+ *           </Table.Body>
+ *         </Table.Table>
+ *       </Table.Surface>
+ *     </Table.Root>
+ *   )
+ * }
+ */
+export function useVirtualizedTable({ items, getItemKey, estimateSize = 34, overscan = 5, paddingStart = 0, paddingEnd = 0, maxHeight = 320, availableHeight = maxHeight, }) {
+    const bodyRef = useRef(null);
+    const virtualizer = useVirtualizer({
+        count: items.length,
+        getScrollElement: () => bodyRef.current,
+        estimateSize: (index) => typeof estimateSize === 'function'
+            ? estimateSize(items[index], index)
+            : estimateSize,
+        getItemKey: (index) => getItemKey(items[index], index),
+        overscan,
+        paddingStart,
+        paddingEnd,
+    });
+    // Filtering or sorting supplies a new array; scrolling alone must not reset it.
+    useLayoutEffect(() => {
+        virtualizer.scrollToOffset(0);
+    }, [items, virtualizer]);
+    const totalSize = virtualizer.getTotalSize();
+    const virtualRows = virtualizer.getVirtualItems();
+    const bodyProps = {
+        ref: bodyRef,
+        style: {
+            height: Math.min(totalSize, maxHeight),
+            maxHeight: availableHeight,
+            overflowY: 'auto',
+        },
+    };
+    const rows = virtualRows.map((row) => ({
+        key: row.key,
+        index: row.index,
+        item: items[row.index],
+        start: row.start,
+        size: row.size,
+        rowProps: { style: { height: row.size } },
+    }));
+    // Table rows stay in normal flow; the caller renders these as spacer rows.
+    const spacers = {
+        before: virtualRows[0]?.start ?? 0,
+        after: virtualRows.length
+            ? totalSize - virtualRows[virtualRows.length - 1].end
+            : 0,
+    };
+    const scrollToIndex = useCallback((index, options) => virtualizer.scrollToIndex(index, { align: 'auto', ...options }), [virtualizer]);
+    return { bodyProps, rows, spacers, scrollToIndex, virtualizer };
+}
+//# sourceMappingURL=useVirtualizedTable.js.map

package/dist/utils/virtualization/useVirtualizedTable.js.map

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

package/package.json

@@ -1,6 +1,66 @@
 {
   "name": "@central-ui/react",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Accessible React components with optional Tailwind CSS style presets",
+  "license": "MIT",
+  "keywords": [
+    "react",
+    "ui",
+    "components",
+    "ark-ui",
+    "unstyled"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "sideEffects": [
+    "./src/presets/**/*.css"
+  ],
+  "files": [
+    "dist",
+    "src/presets",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./presets/shopify-polaris-legacy.css": "./src/presets/shopify-polaris-legacy/shopify-polaris-legacy.css",
+    "./presets/shopify-polaris.css": "./src/presets/shopify-polaris/shopify-polaris.css"
+  },
+  "scripts": {
+    "build": "tsc --project tsconfig.json",
+    "prepack": "npm run build",
+    "typecheck": "tsc --project tsconfig.json --noEmit"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0",
+    "tailwindcss": "^4.2.1"
+  },
+  "peerDependenciesMeta": {
+    "tailwindcss": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
+    "typescript": "6.0.3"
+  },
+  "dependencies": {
+    "@ark-ui/react": "5.39.3",
+    "@base-ui/react": "1.9.0",
+    "@internationalized/date": "3.12.4",
+    "@radix-ui/react-password-toggle-field": "0.2.1",
+    "@tanstack/react-virtual": "3.14.20",
+    "lucide-react": "1.57.0",
+    "react-aria": "3.53.1",
+    "react-aria-components": "1.22.1",
+    "react-resizable-panels": "4.14.5",
+    "tailwind-merge": "3.7.0"
+  }
+}

package/src/presets/shopify-polaris/shopify-polaris-accordion.css

@@ -0,0 +1,28 @@
+/* accordion */
+@layer components {
+  :where(:not([data-style-disabled])) {
+    &:where([data-component='accordion-list']) {
+      @apply flex w-full flex-col overflow-hidden rounded-xl border border-neutral-200 bg-white;
+    }
+
+    &:where([data-component='accordion-item']) {
+      @apply w-full border-b border-neutral-200 last:border-b-0;
+    }
+
+    &:where([data-component='accordion-openbutton']) {
+      @apply flex min-h-10 w-full cursor-pointer items-center justify-between gap-4 bg-white px-3 py-2 text-left text-sm font-medium text-neutral-950 outline-none hover:bg-neutral-50 focus-visible:relative focus-visible:z-1 focus-visible:outline-2 focus-visible:outline-blue-500 disabled:pointer-events-none disabled:bg-neutral-100 disabled:text-neutral-500 disabled:opacity-50;
+    }
+
+    &:where([data-component='accordion-openertitle']) {
+      @apply min-w-0 flex-1;
+    }
+
+    &:where([data-component='accordion-openerindicator']) {
+      @apply h-4 w-fit shrink-0 text-inherit transition-transform data-panel-open:rotate-180;
+    }
+
+    &:where([data-component='accordion-content']) {
+      @apply h-(--accordion-panel-height) overflow-hidden text-sm text-neutral-700 transition-[height] duration-200 data-starting-style:h-0 data-ending-style:h-0;
+    }
+  }
+}