@usefui/components 1.5.3 → 1.6.0

package/src/shimmer/index.tsx

@@ -0,0 +1,64 @@
+"use client";
+
+import React from "react";
+import { TextShimmerWrapper } from "./styles";
+import { IComponentStyling } from "../../../../types";
+
+const DEFAULT_DURATION = 2;
+const DEFAULT_SPREAD = 200;
+const DEFAULT_SHIMMER_COLOR = "var(--font-color-alpha-60)";
+const DEFAULT_BASE_COLOR = "var(--font-color-alpha-30)";
+
+export interface ITextShimmerProperties
+  extends IComponentStyling, React.HTMLAttributes<HTMLSpanElement> {
+  duration?: number;
+  spread?: number;
+  shimmerColor?: string;
+  baseColor?: string;
+}
+
+/**
+ * Shimmer applies an animated shimmer gradient effect to inline text content.
+ *
+ * **Best practices:**
+ *
+ * - Use to indicate loading states for text content.
+ * - Prefer CSS custom properties for `shimmerColor` and `baseColor` to stay consistent with your design tokens.
+ * - Avoid using on large blocks of text; favour short labels or headings.
+ *
+ * @param {ITextShimmerProperties} props - The props for the Shimmer component.
+ * @param {ReactNode} props.children - The text content to apply the shimmer effect to.
+ * @param {boolean} props.raw - Whether the component is unstyled.
+ * @param {number} props.duration - Animation cycle duration in seconds. Defaults to 2.
+ * @param {number} props.spread - Gradient spread width as a percentage. Defaults to 200.
+ * @param {string} props.shimmerColor - Highlight color of the shimmer. Defaults to `--font-color-alpha-60`.
+ * @param {string} props.baseColor - Base text gradient color. Defaults to `--font-color-alpha-30`.
+ * @returns {ReactElement} The Shimmer component.
+ */
+export const Shimmer = (props: ITextShimmerProperties) => {
+  const {
+    children,
+    raw,
+    duration = DEFAULT_DURATION,
+    spread = DEFAULT_SPREAD,
+    shimmerColor = DEFAULT_SHIMMER_COLOR,
+    baseColor = DEFAULT_BASE_COLOR,
+    ...restProps
+  } = props;
+
+  return (
+    <TextShimmerWrapper
+      data-raw={Boolean(raw)}
+      data-duration={duration}
+      data-spread={spread}
+      data-shimmer-color={shimmerColor}
+      data-base-color={baseColor}
+      aria-label={restProps["aria-label"] ?? "shimmer-text"}
+      {...restProps}
+    >
+      {children}
+    </TextShimmerWrapper>
+  );
+};
+
+Shimmer.displayName = "Shimmer";

package/src/shimmer/styles/index.ts

@@ -0,0 +1,33 @@
+import styled, { keyframes } from "styled-components";
+
+const shimmer = keyframes`
+  0% {
+    background-position: 200% center;
+  }
+  100% {
+    background-position: -200% center;
+  }
+`;
+
+export const TextShimmerWrapper = styled.span<{
+  "data-duration": number;
+  "data-spread": number;
+  "data-shimmer-color": string;
+  "data-base-color": string;
+}>`
+  background: linear-gradient(
+    90deg,
+    ${({ "data-base-color": baseColor }) => baseColor} 0%,
+    ${({ "data-shimmer-color": shimmerColor }) => shimmerColor} 40%,
+    ${({ "data-base-color": baseColor }) => baseColor} 60%,
+    ${({ "data-base-color": baseColor }) => baseColor} 100%
+  );
+  background-size: ${({ "data-spread": spread }) => spread}% auto;
+  background-clip: text;
+  -webkit-background-clip: text;
+  -webkit-text-fill-color: transparent;
+  color: transparent;
+  animation: ${shimmer} ${({ "data-duration": duration }) => duration}s linear
+    infinite;
+  display: inline-block;
+`;

package/src/switch/hooks/index.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import React, { useState, createContext, useContext } from "react";
 import { IReactChildren, IComponentAPI } from "../../../../../types";
 
@@ -9,7 +11,9 @@ const defaultComponentAPI = {
 const SwitchContext = createContext<IComponentAPI>(defaultComponentAPI);
 export const useSwitch = () => useContext(SwitchContext);
 
-export const SwitchProvider = ({ children }: IReactChildren): JSX.Element => {
+export const SwitchProvider = ({
+  children,
+}: IReactChildren): React.JSX.Element => {
   const context = useSwitchProvider();
 
   return (

package/src/tabs/hooks/index.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import React, { createContext, useContext, useState } from "react";
 import { IReactChildren, IComponentAPI } from "../../../../../types";
 
@@ -9,7 +11,9 @@ const defaultComponentAPI = {
 const TabsContext = createContext<IComponentAPI>(defaultComponentAPI);
 export const useTabs = () => useContext(TabsContext);
 
-export const TabsProvider = ({ children }: IReactChildren): JSX.Element => {
+export const TabsProvider = ({
+  children,
+}: IReactChildren): React.JSX.Element => {
   const context = useTabsProvider();
 
   return (

package/src/toolbar/hooks/index.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import React, { useState, createContext, useContext } from "react";
 import { IReactChildren, IComponentAPI } from "../../../../../types";
 
@@ -9,7 +11,9 @@ const defaultComponentAPI = {
 const ToolbarContext = createContext<IComponentAPI>(defaultComponentAPI);
 export const useToolbar = () => useContext(ToolbarContext);
 
-export const ToolbarProvider = ({ children }: IReactChildren): JSX.Element => {
+export const ToolbarProvider = ({
+  children,
+}: IReactChildren): React.JSX.Element => {
   const context = useToolbarProvider();
 
   return (

package/src/tree/Tree.stories.tsx

@@ -0,0 +1,139 @@
+import React from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+
+import { Tree } from "..";
+import { ComponentSizeEnum, ComponentVariantEnum } from "../../../../types";
+
+const meta = {
+  title: "Components/Tree",
+  component: Tree,
+  tags: ["autodocs"],
+  decorators: [
+    (Story) => (
+      <div className="m-medium-30">
+        <Story />
+      </div>
+    ),
+  ],
+} satisfies Meta<typeof Tree>;
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  argTypes: {
+    spacing: {
+      options: [
+        ComponentSizeEnum.Small,
+        ComponentSizeEnum.Medium,
+        ComponentSizeEnum.Large,
+      ],
+      control: { type: "radio" },
+    },
+    variant: {
+      options: [
+        ComponentVariantEnum.Primary,
+        ComponentVariantEnum.Secondary,
+        ComponentVariantEnum.Tertiary,
+        ComponentVariantEnum.Mono,
+        ComponentVariantEnum.Border,
+        ComponentVariantEnum.Ghost,
+      ],
+      control: { type: "radio" },
+    },
+    sizing: {
+      options: [
+        ComponentSizeEnum.Small,
+        ComponentSizeEnum.Medium,
+        ComponentSizeEnum.Large,
+      ],
+      control: { type: "radio" },
+    },
+  },
+  render: ({ ...args }) => (
+    <Tree.Root>
+      <Tree>
+        <Tree.Node nodeId="src">
+          <Tree.Trigger nodeId="src">src</Tree.Trigger>
+          <Tree.Content nodeId="src">
+            <Tree.Node level={1} nodeId="index.ts">
+              <Tree.Trigger nodeId="index.ts">index.ts</Tree.Trigger>
+            </Tree.Node>
+          </Tree.Content>
+        </Tree.Node>
+      </Tree>
+    </Tree.Root>
+  ),
+};
+
+export const DefaultOpen: Story = {
+  render: ({ ...args }) => (
+    <Tree.Root>
+      <Tree>
+        <Tree.Node nodeId="src">
+          <Tree.Trigger nodeId="src">src</Tree.Trigger>
+          <Tree.Content nodeId="src" defaultOpen>
+            <Tree.Node level={1} nodeId="index.ts">
+              <Tree.Trigger nodeId="index.ts">index.ts</Tree.Trigger>
+            </Tree.Node>
+          </Tree.Content>
+        </Tree.Node>
+      </Tree>
+    </Tree.Root>
+  ),
+};
+
+export const Nested: Story = {
+  render: ({ ...args }) => (
+    <Tree.Root>
+      <Tree>
+        <Tree.Node nodeId="src">
+          <Tree.Trigger nodeId="src">src</Tree.Trigger>
+          <Tree.Content nodeId="src" defaultOpen>
+            <Tree.Node level={1} nodeId="components">
+              <Tree.Trigger nodeId="components">components</Tree.Trigger>
+              <Tree.Content nodeId="components" defaultOpen>
+                <Tree.Node level={2} nodeId="button.ts">
+                  <Tree.Trigger nodeId="button.ts">button.ts</Tree.Trigger>
+                </Tree.Node>
+                <Tree.Node level={2} nodeId="card.ts" isLast>
+                  <Tree.Trigger nodeId="card.ts">card.ts</Tree.Trigger>
+                </Tree.Node>
+              </Tree.Content>
+            </Tree.Node>
+            <Tree.Node level={1} nodeId="index.ts" isLast>
+              <Tree.Trigger nodeId="index.ts">index.ts</Tree.Trigger>
+            </Tree.Node>
+          </Tree.Content>
+        </Tree.Node>
+      </Tree>
+    </Tree.Root>
+  ),
+};
+
+export const Group: Story = {
+  render: ({ ...args }) => (
+    <Tree.Root>
+      <Tree>
+        {["src", "public", "tests", "docs", "config"].map(
+          (item, index, array) => (
+            <Tree.Node
+              key={item}
+              nodeId={item}
+              isLast={index === array.length - 1}
+            >
+              <Tree.Trigger nodeId={item}>{item}</Tree.Trigger>
+              <Tree.Content nodeId={item}>
+                <Tree.Node level={1} nodeId={`${item}/index.ts`} isLast>
+                  <Tree.Trigger nodeId={`${item}/index.ts`}>
+                    index.ts
+                  </Tree.Trigger>
+                </Tree.Node>
+              </Tree.Content>
+            </Tree.Node>
+          ),
+        )}
+      </Tree>
+    </Tree.Root>
+  ),
+};

package/src/tree/hooks/tree-node-provider.tsx

@@ -0,0 +1,50 @@
+"use client";
+
+import React, { createContext, useContext } from "react";
+import { IReactChildren, IComponentAPI } from "../../../../../types";
+
+const defaultTreeNodeAPI: IComponentAPI = {
+  id: "",
+  states: {},
+  methods: {},
+};
+
+const TreeNodeContext = createContext<IComponentAPI>(defaultTreeNodeAPI);
+export const useTreeNode = () => useContext(TreeNodeContext);
+
+export interface ITreeNodeProviderProperties extends IReactChildren {
+  nodeId: string;
+  level: number;
+  isLast: boolean;
+}
+
+export const TreeNodeProvider = ({
+  children,
+  nodeId,
+  level,
+  isLast,
+}: ITreeNodeProviderProperties): React.JSX.Element => {
+  const context = useTreeNodeProviderContext({ nodeId, level, isLast });
+
+  return (
+    <TreeNodeContext.Provider value={context}>
+      {children}
+    </TreeNodeContext.Provider>
+  );
+};
+
+function useTreeNodeProviderContext({
+  nodeId,
+  level,
+  isLast,
+}: Omit<ITreeNodeProviderProperties, "children">): IComponentAPI {
+  return {
+    id: nodeId,
+    states: {
+      nodeId,
+      level,
+      isLast,
+    },
+    methods: {},
+  };
+}

package/src/tree/hooks/tree-provider.tsx

@@ -0,0 +1,75 @@
+"use client";
+
+import React, { useState, createContext, useContext } from "react";
+import { IReactChildren, IComponentAPI } from "../../../../../types";
+
+// ─── Tree Context ─────────────────────────────────────────────────────────────
+
+const defaultTreeAPI: IComponentAPI = {
+  id: "",
+  states: {},
+  methods: {},
+};
+
+const TreeContext = createContext<IComponentAPI>(defaultTreeAPI);
+export const useTree = () => useContext(TreeContext);
+
+export interface ITreeProviderProperties extends IReactChildren {
+  defaultExpandedIds?: string[];
+  onSelectionChange?: (ids: string[]) => void;
+}
+
+export const TreeProvider = ({
+  children,
+  defaultExpandedIds = [],
+  onSelectionChange,
+}: ITreeProviderProperties): React.JSX.Element => {
+  const context = useTreeProviderContext({
+    defaultExpandedIds,
+    onSelectionChange,
+  });
+
+  return (
+    <TreeContext.Provider value={context}>{children}</TreeContext.Provider>
+  );
+};
+
+function useTreeProviderContext({
+  defaultExpandedIds,
+  onSelectionChange,
+}: Omit<ITreeProviderProperties, "children">): IComponentAPI {
+  const treeId = React.useId();
+  const [expandedIds, setExpandedIds] = useState<Set<string>>(
+    () => new Set(defaultExpandedIds),
+  );
+  const [selectedIds, setSelectedIds] = useState<Set<string>>(() => new Set());
+
+  return {
+    id: treeId,
+    states: {
+      expandedIds,
+      selectedIds,
+    },
+    methods: {
+      isExpanded: (id: string): boolean => expandedIds.has(id),
+      isSelected: (id: string): boolean => selectedIds.has(id),
+      toggleExpanded: (id: string): void => {
+        setExpandedIds((prev) => {
+          const next = new Set(prev);
+          next.has(id) ? next.delete(id) : next.add(id);
+          return next;
+        });
+      },
+      toggleSelected: (id: string): void => {
+        setSelectedIds((prev) => {
+          const next = new Set(prev);
+          next.has(id) ? next.delete(id) : next.add(id);
+          onSelectionChange?.(Array.from(next));
+          return next;
+        });
+      },
+      getTreeId: ({ nodeId, type }: Record<string, string>): string =>
+        `${treeId}-${type}-${nodeId}`,
+    },
+  };
+}

package/src/tree/index.tsx

@@ -0,0 +1,231 @@
+"use client";
+
+import React from "react";
+
+import { TreeProvider, useTree } from "./hooks/tree-provider";
+import { TreeNodeProvider, useTreeNode } from "./hooks/tree-node-provider";
+
+import { Button, IButtonProperties } from "../button";
+import { TreeView, TreeItem, TreeNodeContent } from "./styles";
+
+import {
+  IReactChildren,
+  IComponentSpacing,
+  ComponentVariantEnum,
+} from "../../../../types";
+
+export interface ITreeComposition {
+  Root: typeof TreeRoot;
+  Node: typeof TreeNode;
+  Trigger: typeof TreeTrigger;
+  Content: typeof TreeContent;
+}
+
+export interface ITreeProperties
+  extends IComponentSpacing, React.ComponentProps<"ul"> {}
+
+export interface ITreeRootProperties extends IReactChildren {
+  defaultExpandedIds?: string[];
+  onSelectionChange?: (ids: string[]) => void;
+}
+
+export interface ITreeNodeProperties
+  extends IComponentSpacing, React.ComponentProps<"li"> {
+  nodeId: string;
+  level?: number;
+  isLast?: boolean;
+}
+
+export interface ITreeTriggerProperties extends Omit<
+  IButtonProperties,
+  "value"
+> {
+  nodeId: string;
+}
+
+export interface ITreeContentProperties
+  extends IComponentSpacing, React.ComponentProps<"ul"> {
+  nodeId: string;
+  defaultOpen?: boolean;
+}
+
+/**
+ * Tree is used to display a hierarchical list of items.
+ *
+ * **Best practices:**
+ *
+ * - Use a clear and descriptive label for each tree node.
+ * - Ensure that the tree can be operated using only the keyboard.
+ * - Ensure that the focus is properly managed when nodes are expanded/collapsed.
+ *
+ * @param {ITreeProperties} props - The props for the Tree component.
+ * @param {ReactNode} props.children - The content to be rendered inside the tree.
+ * @returns {ReactElement} The Tree component.
+ */
+const Tree = (props: ITreeProperties) => {
+  const { children, ...restProps } = props;
+  const { id } = useTree();
+
+  return (
+    <TreeView id={id} role="tree" {...restProps}>
+      {children}
+    </TreeView>
+  );
+};
+Tree.displayName = "Tree";
+
+const TreeRoot = ({
+  children,
+  defaultExpandedIds,
+  onSelectionChange,
+}: ITreeRootProperties) => {
+  return (
+    <TreeProvider
+      defaultExpandedIds={defaultExpandedIds}
+      onSelectionChange={onSelectionChange}
+    >
+      {children}
+    </TreeProvider>
+  );
+};
+TreeRoot.displayName = "Tree.Root";
+
+/**
+ * Tree.Node is used to wrap each node of the tree.
+ *
+ * **Best practices:**
+ *
+ * - Provide a unique nodeId for each node.
+ * - Use the level prop to indicate the depth of the node in the hierarchy.
+ *
+ * @param {ITreeNodeProperties} props - The props for the Tree.Node component.
+ * @param {string} props.nodeId - The unique identifier for the node.
+ * @param {number} props.level - The depth level of the node. Defaults to 0.
+ * @param {boolean} props.isLast - Whether the node is the last in its siblings. Defaults to false.
+ * @param {ReactNode} props.children - The content to be rendered inside the node.
+ * @returns {ReactElement} The Tree.Node component.
+ */
+const TreeNode = (props: ITreeNodeProperties) => {
+  const { nodeId, level = 0, isLast = false, children, ...restProps } = props;
+
+  return (
+    <TreeNodeProvider nodeId={nodeId} level={level} isLast={isLast}>
+      <TreeItem role="treeitem" aria-level={level + 1} {...restProps}>
+        {children}
+      </TreeItem>
+    </TreeNodeProvider>
+  );
+};
+TreeNode.displayName = "Tree.Node";
+
+/**
+ * Tree.Trigger is used to trigger the expansion and collapse of the associated Tree.Content component.
+ *
+ * **Best practices:**
+ *
+ * - Use a clear and descriptive label for the trigger.
+ * - Ensure that the trigger can be operated using only the keyboard.
+ * - Ensure that the focus is properly managed when the trigger is activated.
+ *
+ * @param {ITreeTriggerProperties} props - The props for the Tree.Trigger component.
+ * @param {string} props.nodeId - The value used to bind the Tree.Trigger and Tree.Content components.
+ * @param {ReactNode} props.children - The content to be rendered inside the trigger.
+ * @returns {ReactElement} The Tree.Trigger component.
+ */
+const TreeTrigger = (props: ITreeTriggerProperties) => {
+  const { nodeId, disabled, onClick, children, ...restProps } = props;
+
+  const { methods } = useTree();
+  const { getTreeId, toggleExpanded, toggleSelected } = methods;
+
+  const isExpanded = methods.isExpanded && methods.isExpanded(nodeId);
+  const isSelected = methods.isSelected && methods.isSelected(nodeId);
+
+  const IdHandler = {
+    trigger: getTreeId && getTreeId({ nodeId, type: "trigger" }),
+    content: getTreeId && getTreeId({ nodeId, type: "content" }),
+  };
+
+  const { states: nodeStates } = useTreeNode();
+  const level = nodeStates.level ?? 0;
+
+  const handleClick = (event: React.MouseEvent<HTMLButtonElement>) => {
+    if (!disabled) {
+      onClick && onClick(event);
+      toggleExpanded && toggleExpanded(nodeId);
+      toggleSelected && toggleSelected(nodeId);
+    }
+  };
+
+  return (
+    <Button
+      id={String(IdHandler.trigger)}
+      disabled={disabled ?? false}
+      onClick={handleClick}
+      data-state={isExpanded ? "expanded" : "collapsed"}
+      data-selected={isSelected || undefined}
+      variant={props.variant ?? ComponentVariantEnum.Ghost}
+      style={{ paddingLeft: `calc(${level} * 1rem + 0.5rem)` }}
+      rawicon
+      {...restProps}
+    >
+      {children}
+    </Button>
+  );
+};
+TreeTrigger.displayName = "Tree.Trigger";
+
+/**
+ * Tree.Content is used to contain the children of the associated Tree.Trigger component.
+ *
+ * **Best practices:**
+ *
+ * - Ensure that the content is hidden when the associated node is collapsed.
+ * - Ensure that the content is properly focused when the associated node is expanded.
+ *
+ * @param {ITreeContentProperties} props - The props for the Tree.Content component.
+ * @param {string} props.nodeId - The value used to bind the Tree.Content and Tree.Trigger components.
+ * @param {boolean} props.defaultOpen - The initial open state of the content. Defaults to false.
+ * @param {ReactNode} props.children - The content to be rendered inside the node content.
+ * @returns {ReactElement} The Tree.Content component.
+ */
+const TreeContent = (props: ITreeContentProperties) => {
+  const { nodeId, defaultOpen = false, children, ...restProps } = props;
+
+  const { methods } = useTree();
+  const { getTreeId, toggleExpanded } = methods;
+
+  const isExpanded = methods.isExpanded && methods.isExpanded(nodeId);
+
+  const IdHandler = {
+    trigger: getTreeId && getTreeId({ nodeId, type: "trigger" }),
+    content: getTreeId && getTreeId({ nodeId, type: "content" }),
+  };
+
+  React.useEffect(() => {
+    if (defaultOpen && !isExpanded && toggleExpanded) toggleExpanded(nodeId);
+  }, []);
+
+  if (isExpanded)
+    return (
+      <TreeNodeContent
+        role="group"
+        id={String(IdHandler.content)}
+        aria-labelledby={String(IdHandler.trigger)}
+        data-nodeId={nodeId}
+        {...restProps}
+      >
+        {children}
+      </TreeNodeContent>
+    );
+
+  return <React.Fragment />;
+};
+TreeContent.displayName = "Tree.Content";
+
+Tree.Root = TreeRoot;
+Tree.Node = TreeNode;
+Tree.Trigger = TreeTrigger;
+Tree.Content = TreeContent;
+
+export { Tree, TreeRoot, TreeNode, TreeTrigger, TreeContent };

package/src/tree/styles/index.ts

@@ -0,0 +1,23 @@
+import styled from "styled-components";
+
+export const TreeView = styled.ul<any>`
+  display: flex;
+  flex-direction: column;
+  list-style: none;
+  margin: 0;
+  padding: 0;
+`;
+
+export const TreeItem = styled.li<any>`
+  display: flex;
+  flex-direction: column;
+  list-style: none;
+`;
+
+export const TreeNodeContent = styled.ul<any>`
+  display: flex;
+  flex-direction: column;
+  list-style: none;
+  margin: 0;
+  padding: 0;
+`;

package/tsconfig.build.json

@@ -0,0 +1,20 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "noEmit": false,
+    "outDir": "./dist",
+    "declaration": true,
+    "declarationDir": "./dist",
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "exclude": [
+    "node_modules",
+    "**/*.test.ts",
+    "**/*.test.tsx",
+    "**/*.spec.ts",
+    "**/*.spec.tsx",
+    "**/*.stories.ts",
+    "**/*.stories.tsx"
+  ]
+}