@proyecto-viviana/solidaria-components 0.2.9 → 0.3.0

package/src/Collection.tsx

@@ -5,16 +5,9 @@
  * Section / Header / Group.
  */
 
-import {
-  type JSX,
-  createContext,
-  createMemo,
-  splitProps,
-  useContext,
-  For,
-} from 'solid-js';
-import type { Key } from '@proyecto-viviana/solid-stately';
-import type { DragTypes, DropOperation, DropTarget } from '@proyecto-viviana/solid-stately';
+import { type JSX, createContext, createMemo, splitProps, useContext, For } from "solid-js";
+import type { Key } from "@proyecto-viviana/solid-stately";
+import type { DragTypes, DropOperation, DropTarget } from "@proyecto-viviana/solid-stately";
 import {
   Collection as AriaCollection,
   CollectionBuilder as AriaCollectionBuilder,
@@ -22,44 +15,48 @@ import {
   createBranchComponent,
   type CollectionProps as AriaCollectionProps,
   type CollectionBuilderProps as AriaCollectionBuilderProps,
-} from '@proyecto-viviana/solidaria';
+} from "@proyecto-viviana/solidaria";
 import {
   type ClassNameOrFunction,
   type StyleOrFunction,
   type SlotProps,
   useRenderProps,
   filterDOMProps,
-} from './utils';
-
-// ============================================
-// TYPES
-// ============================================
+} from "./utils";
 
 export interface CollectionPrimitiveRenderProps {
   /** Whether the primitive has visible children content. */
   hasChildren: boolean;
 }
 
+type RefLike<T> = ((el: T) => void) | { current?: T | null } | undefined;
+
+function assignRef<T>(ref: RefLike<T>, el: T): void {
+  if (!ref) return;
+  if (typeof ref === "function") ref(el);
+  else ref.current = el;
+}
+
 export interface CollectionDropTargetDelegate {
   getDropTargetFromPoint(
     x: number,
     y: number,
-    isValidDropTarget: (target: DropTarget) => boolean
+    isValidDropTarget: (target: DropTarget) => boolean,
   ): DropTarget | null;
   getDropOperation(
     target: DropTarget,
     types: DragTypes,
-    allowedOperations: DropOperation[]
+    allowedOperations: DropOperation[],
   ): DropOperation;
   getKeyboardNavigationTarget?(
     target: DropTarget | null,
-    direction: 'next' | 'previous',
-    isValidDropTarget: (target: DropTarget) => boolean
+    direction: "next" | "previous",
+    isValidDropTarget: (target: DropTarget) => boolean,
   ): DropTarget | null;
   getKeyboardPageNavigationTarget?(
     target: DropTarget | null,
-    direction: 'next' | 'previous',
-    isValidDropTarget: (target: DropTarget) => boolean
+    direction: "next" | "previous",
+    isValidDropTarget: (target: DropTarget) => boolean,
   ): DropTarget | null;
 }
 
@@ -73,7 +70,10 @@ export interface CollectionRendererContextValue<T> {
   /** Optional drop target delegate used by DnD-aware collection paths. */
   dropTargetDelegate?: CollectionDropTargetDelegate;
   /** Optional drop indicator renderer for DnD-aware collection paths. */
-  renderDropIndicator?: (index: number, position: 'before' | 'after' | 'on') => JSX.Element | undefined;
+  renderDropIndicator?: (
+    index: number,
+    position: "before" | "after" | "on",
+  ) => JSX.Element | undefined;
 }
 
 export type CollectionEntry<T> = T | CollectionSection<T>;
@@ -84,7 +84,7 @@ export interface CollectionSection<T> {
   /** Optional section header title. */
   title?: JSX.Element;
   /** Optional aria-label for section grouping. */
-  'aria-label'?: string;
+  "aria-label"?: string;
   /** Items contained in the section. */
   items: T[];
 }
@@ -92,6 +92,8 @@ export interface CollectionSection<T> {
 export interface SectionProps extends SlotProps {
   /** Section contents, usually Header + Group/items. */
   children?: JSX.Element;
+  /** Ref for the section element. */
+  ref?: RefLike<HTMLDivElement>;
   /** The CSS className for the element. */
   class?: ClassNameOrFunction<CollectionPrimitiveRenderProps>;
   /** The inline style for the element. */
@@ -102,7 +104,7 @@ export interface HeaderProps extends SlotProps {
   /** Header contents, usually section title text. */
   children?: JSX.Element;
   /** Optional heading level when rendered as a heading role. */
-  'aria-level'?: number;
+  "aria-level"?: number;
   /** The CSS className for the element. */
   class?: ClassNameOrFunction<CollectionPrimitiveRenderProps>;
   /** The inline style for the element. */
@@ -126,13 +128,21 @@ interface SectionContextValue {
 export interface CollectionBranchProps<T> {
   collection: Iterable<T>;
   parent?: unknown;
-  renderDropIndicator?: (target: { type: 'item'; key: Key; dropPosition: 'before' | 'after' | 'on' }) => JSX.Element | undefined;
+  renderDropIndicator?: (target: {
+    type: "item";
+    key: Key;
+    dropPosition: "before" | "after" | "on";
+  }) => JSX.Element | undefined;
 }
 
 export interface CollectionRootProps<T> {
   collection: Iterable<T>;
   persistedKeys?: Set<Key> | null;
-  renderDropIndicator?: (target: { type: 'item'; key: Key; dropPosition: 'before' | 'after' | 'on' }) => JSX.Element | undefined;
+  renderDropIndicator?: (target: {
+    type: "item";
+    key: Key;
+    dropPosition: "before" | "after" | "on";
+  }) => JSX.Element | undefined;
 }
 
 export interface CollectionRenderer<T = unknown> {
@@ -143,11 +153,8 @@ export interface CollectionRenderer<T = unknown> {
   CollectionBranch: (props: CollectionBranchProps<T>) => JSX.Element;
 }
 
-// ============================================
-// CONTEXT
-// ============================================
-
-export const CollectionRendererContext = createContext<CollectionRendererContextValue<unknown> | null>(null);
+export const CollectionRendererContext =
+  createContext<CollectionRendererContextValue<unknown> | null>(null);
 export const SelectableCollectionContext = CollectionRendererContext;
 export const SectionContext = createContext<SectionContextValue | null>(null);
 export const GroupContext = createContext<Partial<GroupProps> | null>(null);
@@ -158,12 +165,12 @@ export function useCollectionRenderer<T>(): CollectionRendererContextValue<T> |
   return useContext(CollectionRendererContext) as CollectionRendererContextValue<T> | null;
 }
 
-// ============================================
-// HELPERS
-// ============================================
-
 export function isCollectionSection<T>(entry: CollectionEntry<T>): entry is CollectionSection<T> {
-  return typeof entry === 'object' && entry !== null && Array.isArray((entry as CollectionSection<T>).items);
+  return (
+    typeof entry === "object" &&
+    entry !== null &&
+    Array.isArray((entry as CollectionSection<T>).items)
+  );
 }
 
 export function flattenCollectionEntries<T>(entries: CollectionEntry<T>[]): T[] {
@@ -177,23 +184,27 @@ export function flattenCollectionEntries<T>(entries: CollectionEntry<T>[]): T[]
 
 function renderCollectionItems<T>(
   collection: Iterable<T>,
-  renderDropIndicator?: (target: { type: 'item'; key: Key; dropPosition: 'before' | 'after' | 'on' }) => JSX.Element | undefined
+  renderDropIndicator?: (target: {
+    type: "item";
+    key: Key;
+    dropPosition: "before" | "after" | "on";
+  }) => JSX.Element | undefined,
 ): JSX.Element {
   const items = Array.from(collection);
   return (
     <For each={items}>
       {(item, index) => {
         const node = item as { type?: unknown; key?: Key };
-        if (node.type === 'content') {
+        if (node.type === "content") {
           // Content rows are rendered by their owning item/section branch.
           return <></>;
         }
         const key = node.key ?? index();
         return (
           <>
-            {renderDropIndicator?.({ type: 'item', key, dropPosition: 'before' })}
-            {(item as unknown as JSX.Element)}
-            {renderDropIndicator?.({ type: 'item', key, dropPosition: 'after' })}
+            {renderDropIndicator?.({ type: "item", key, dropPosition: "before" })}
+            {item as unknown as JSX.Element}
+            {renderDropIndicator?.({ type: "item", key, dropPosition: "after" })}
           </>
         );
       }}
@@ -220,24 +231,21 @@ export function Collection<T>(props: AriaCollectionProps<T>): unknown {
 
 export { createLeafComponent, createBranchComponent };
 
-// ============================================
-// COMPONENTS
-// ============================================
-
 /**
  * A semantic section wrapper for grouped collection content.
  */
 export function Section(props: SectionProps): JSX.Element {
   const sectionContext = useContext(SectionContext);
   if (sectionContext) {
-    const nodeEnv = (globalThis as { process?: { env?: { NODE_ENV?: string } } }).process?.env?.NODE_ENV;
-    if (nodeEnv !== 'production') {
+    const nodeEnv = (globalThis as { process?: { env?: { NODE_ENV?: string } } }).process?.env
+      ?.NODE_ENV;
+    if (nodeEnv !== "production") {
       console.warn(`<Section> is deprecated. Please use <${sectionContext.name}> instead.`);
     }
-    return sectionContext.render(props, 'solidaria-Section');
+    return sectionContext.render(props, "solidaria-Section");
   }
 
-  const [local, domProps] = splitProps(props, ['children', 'class', 'style', 'slot']);
+  const [local, domProps] = splitProps(props, ["children", "class", "style", "slot", "ref"]);
 
   const renderValues = createMemo<CollectionPrimitiveRenderProps>(() => ({
     hasChildren: local.children != null,
@@ -248,15 +256,16 @@ export function Section(props: SectionProps): JSX.Element {
       children: local.children,
       class: local.class,
       style: local.style,
-      defaultClassName: 'solidaria-Section',
+      defaultClassName: "solidaria-Section",
     },
-    renderValues
+    renderValues,
   );
 
   const filteredDomProps = createMemo(() => filterDOMProps(domProps, { global: true }));
 
   return (
     <div
+      ref={(el) => assignRef(local.ref, el)}
       {...filteredDomProps()}
       class={renderProps.class()}
       style={renderProps.style()}
@@ -272,7 +281,7 @@ export function Section(props: SectionProps): JSX.Element {
  * A header/title primitive for collection sections.
  */
 export function Header(props: HeaderProps): JSX.Element {
-  const [local, domProps] = splitProps(props, ['children', 'class', 'style', 'slot']);
+  const [local, domProps] = splitProps(props, ["children", "class", "style", "slot"]);
 
   const renderValues = createMemo<CollectionPrimitiveRenderProps>(() => ({
     hasChildren: local.children != null,
@@ -283,9 +292,9 @@ export function Header(props: HeaderProps): JSX.Element {
       children: local.children,
       class: local.class,
       style: local.style,
-      defaultClassName: 'solidaria-Header',
+      defaultClassName: "solidaria-Header",
     },
-    renderValues
+    renderValues,
   );
 
   const filteredDomProps = createMemo(() => filterDOMProps(domProps, { global: true }));
@@ -308,7 +317,7 @@ export function Header(props: HeaderProps): JSX.Element {
  * A grouping primitive for section item containers.
  */
 export function Group(props: GroupProps): JSX.Element {
-  const [local, domProps] = splitProps(props, ['children', 'class', 'style', 'slot']);
+  const [local, domProps] = splitProps(props, ["children", "class", "style", "slot"]);
 
   const renderValues = createMemo<CollectionPrimitiveRenderProps>(() => ({
     hasChildren: local.children != null,
@@ -319,9 +328,9 @@ export function Group(props: GroupProps): JSX.Element {
       children: local.children,
       class: local.class,
       style: local.style,
-      defaultClassName: 'solidaria-Group',
+      defaultClassName: "solidaria-Group",
     },
-    renderValues
+    renderValues,
   );
 
   const filteredDomProps = createMemo(() => filterDOMProps(domProps, { global: true }));