gbs-add-block 1.2.18 → 1.3.0

package/README.md

@@ -1,4 +1,4 @@
-# GBS Building Blocks 2.0 (v1.2.18)
+# GBS Building Blocks 2.0 (v1.3.0)
 
 Latest and upgraded version of GBS building blocks with headless UI and removed dependencies.
 
@@ -10,7 +10,7 @@ For detailed documentation on usage and props, Please visit: [Building Block Doc
     
 New Beta Components are avilable for testing and feedback, Please visit: [Building Block Documentation v2.0.0 beta](https://gramprokit.vercel.app/2.0.0-beta)
 
-## What's New 🎉 (Ver 1.2.18)
+## What's New 🎉 (Ver 1.3.0)
 
 - Update Candidate for next major change 2.0.0
 

package/index.cjs

@@ -56,12 +56,22 @@ const CONFIG = {
     "Popover",
     "Card",
     "Skeleton",
+    "NumberInput",
+    "RadioGroup",
+    "Switch",
+    "Accordion",
+    "Alert",
+    "Avatar",
+    "Badge",
+    "Progress",
   ],
   // Beta folder names that are not simply the lowercased component name.
   betaFolders: {
     DataGrid: "data-grid",
     DatePicker: "date-picker",
     FileUploader: "file-uploader",
+    NumberInput: "number-input",
+    RadioGroup: "radio-group",
   },
   // Define component dependencies
   dependencies: {
@@ -89,8 +99,7 @@ const MANIFEST_FILE = ".install-manifest.json";
  * component-lib.
  */
 const TESTS_DIR = "__tests__";
-const isTestPath = (filePath) =>
-  filePath.split(/[\\/]/).includes(TESTS_DIR);
+const isTestPath = (filePath) => filePath.split(/[\\/]/).includes(TESTS_DIR);
 
 const normalizeComponent = (component, availableComponents) =>
   availableComponents.find(
@@ -199,7 +208,9 @@ const installShared = async (destPath, { force = false } = {}) => {
       console.error(
         "  Installing it would downgrade the folder and break the components already here.",
       );
-      console.error("  Update the CLI, or re-run with --force to overwrite it anyway.");
+      console.error(
+        "  Update the CLI, or re-run with --force to overwrite it anyway.",
+      );
       process.exit(1);
     }
 
@@ -230,16 +241,23 @@ const installShared = async (destPath, { force = false } = {}) => {
 
   const files = listFiles(src);
   for (const file of files) {
-    await fs.copy(path.join(src, file), path.join(dest, file), { overwrite: true });
+    await fs.copy(path.join(src, file), path.join(dest, file), {
+      overwrite: true,
+    });
   }
 
   // Remove what an older version left behind, but only files we installed and
   // the user has not since changed.
   if (manifest) {
-    const removed = Object.keys(manifest.files).filter((file) => !files.includes(file));
+    const removed = Object.keys(manifest.files).filter(
+      (file) => !files.includes(file),
+    );
     for (const file of removed) {
       const target = path.join(dest, file);
-      if (fs.existsSync(target) && (force || manifest.files[file] === sha256(target))) {
+      if (
+        fs.existsSync(target) &&
+        (force || manifest.files[file] === sha256(target))
+      ) {
         await fs.remove(target);
       }
     }
@@ -285,7 +303,10 @@ const checkComponentExists = (component, destPath, beta = false) => {
 
 const copyComponent = async (component, destPath, beta = false) => {
   try {
-    const componentSrc = path.join(getSourcePath(beta), folderFor(component, beta));
+    const componentSrc = path.join(
+      getSourcePath(beta),
+      folderFor(component, beta),
+    );
     const componentDest = path.join(destPath, folderFor(component, beta));
 
     if (!fs.existsSync(componentSrc)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gbs-add-block",
-  "version": "1.2.18",
+  "version": "1.3.0",
   "description": "React Component Library",
   "type": "module",
   "files": [

package/source/beta-components/accordion/README.md

@@ -0,0 +1,45 @@
+# Accordion
+
+Sections that open and close, built on native `<details>` and `<summary>`, for
+React 19 and styled to match the rest of the library. No runtime dependencies
+besides React.
+
+```ts
+import { Accordion, AccordionItem } from "@/components/accordion";
+import "@/components/accordion/styles.css";
+```
+
+```tsx
+<Accordion
+  defaultValue={["shipping"]}
+  items={[
+    { value: "shipping", title: "Shipping", content: <p>Two to five days.</p> },
+    { value: "returns", title: "Returns", content: <p>Thirty days, no questions.</p> },
+  ]}
+/>
+
+<Accordion multiple variant="contained">
+  <AccordionItem value="one" title="Details" meta={<Badge count={3} />}>
+    …
+  </AccordionItem>
+</Accordion>
+```
+
+**Accordion:** `value` / `defaultValue` / `onValueChange` (string arrays),
+`items` or `<AccordionItem>` children, `multiple`, `collapsible`, `variant`
+(`separated` `contained` `plain`), `size`, `iconPosition`, `classNames`, `ref`.
+
+**AccordionItem:** `value`, `title`, `description`, `children`, `meta`, `icon`,
+`disabled`, `classNames` (`root` `header` `title` `description` `icon`
+`content` `body`), `ref` (the `<details>`).
+
+The browser owns the disclosure: the header is focusable, Enter and Space work,
+the panel is out of the accessibility tree while closed, and Ctrl+F finds text
+inside a closed panel where the browser supports it. What the component owns is
+the group — which panel is open, and whether the last one may be closed —
+because `<details name>` alone cannot express that and gives no value to store.
+
+Opening animates in browsers that have `interpolate-size` and
+`::details-content`, and simply shows and hides everywhere else.
+
+`toggleOpen` and `normalizeOpen` are exported from the framework-free `core`.

package/source/beta-components/accordion/__tests__/core.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, it } from "vitest";
+import { normalizeOpen, toggleOpen } from "../core/open";
+
+describe("toggleOpen", () => {
+  describe("one at a time", () => {
+    it("opens a panel and closes whatever was open", () => {
+      expect(toggleOpen(["a"], "b")).toEqual(["b"]);
+    });
+
+    it("closes the open panel when pressed again", () => {
+      expect(toggleOpen(["a"], "a")).toEqual([]);
+    });
+
+    it("keeps it open when the accordion cannot be empty", () => {
+      // Panels that are the whole page: closing the last leaves a dead end.
+      expect(toggleOpen(["a"], "a", { collapsible: false })).toEqual(["a"]);
+    });
+  });
+
+  describe("several at a time", () => {
+    it("adds and removes without touching the others", () => {
+      expect(toggleOpen(["a"], "b", { multiple: true })).toEqual(["a", "b"]);
+      expect(toggleOpen(["a", "b"], "a", { multiple: true })).toEqual(["b"]);
+    });
+
+    it("keeps the order panels were opened in", () => {
+      expect(toggleOpen(["b"], "a", { multiple: true })).toEqual(["b", "a"]);
+    });
+
+    it("refuses to close the last one when the accordion cannot be empty", () => {
+      expect(toggleOpen(["a"], "a", { multiple: true, collapsible: false })).toEqual(["a"]);
+      // Any other panel is still free to close, because one stays open.
+      expect(toggleOpen(["a", "b"], "a", { multiple: true, collapsible: false })).toEqual(["b"]);
+    });
+  });
+});
+
+describe("normalizeOpen", () => {
+  const values = ["a", "b", "c"];
+
+  it("drops values the accordion does not have", () => {
+    expect(normalizeOpen(["a", "z"], values, { multiple: true })).toEqual(["a"]);
+  });
+
+  it("keeps only the first for a single accordion", () => {
+    // Otherwise it starts showing two panels and can never show two again.
+    expect(normalizeOpen(["a", "b"], values)).toEqual(["a"]);
+  });
+
+  it("opens the first panel when the accordion cannot be empty", () => {
+    expect(normalizeOpen([], values, { collapsible: false })).toEqual(["a"]);
+    expect(normalizeOpen([], values)).toEqual([]);
+  });
+
+  it("has nothing to open when there are no panels", () => {
+    expect(normalizeOpen([], [], { collapsible: false })).toEqual([]);
+  });
+});

package/source/beta-components/accordion/core/index.ts

@@ -0,0 +1,2 @@
+export { normalizeOpen, toggleOpen, type ToggleOptions } from "./open";
+export type * from "./types";

package/source/beta-components/accordion/core/open.ts

@@ -0,0 +1,56 @@
+/**
+ * Which panels are open after a header is pressed.
+ *
+ * Three rules, and every accordion gets at least one of them wrong at some
+ * point, which is why they are here rather than spread through the component:
+ *
+ * `multiple` decides whether opening one closes the others. `collapsible`
+ * decides whether the open one can be closed by pressing it again — a
+ * non-collapsible accordion always has exactly one panel open, which is what
+ * you want when the panels are the whole content of the page and an empty page
+ * would be a dead end.
+ *
+ * Order is kept as panels were opened, so a caller storing the value can tell
+ * which one was opened last.
+ */
+export interface ToggleOptions {
+  multiple?: boolean;
+  collapsible?: boolean;
+}
+
+export function toggleOpen(
+  open: readonly string[],
+  value: string,
+  { multiple = false, collapsible = true }: ToggleOptions = {},
+): string[] {
+  const isOpen = open.includes(value);
+
+  if (!multiple) {
+    if (!isOpen) return [value];
+    return collapsible ? [] : [value];
+  }
+
+  if (!isOpen) return [...open, value];
+  // The last panel of a non-collapsible accordion stays put; closing any other
+  // one is fine, because something is still open afterwards.
+  if (!collapsible && open.length === 1) return [...open];
+  return open.filter((item) => item !== value);
+}
+
+/**
+ * The starting value, trimmed to what the settings allow.
+ *
+ * A single accordion given three open panels, or a non-collapsible one given
+ * none, would otherwise start in a state it can never return to once the user
+ * touches it.
+ */
+export function normalizeOpen(
+  open: readonly string[],
+  values: readonly string[],
+  { multiple = false, collapsible = true }: ToggleOptions = {},
+): string[] {
+  const known = open.filter((value) => values.includes(value));
+  const trimmed = multiple ? known : known.slice(0, 1);
+  if (trimmed.length === 0 && !collapsible && values.length > 0) return [values[0]];
+  return trimmed;
+}

package/source/beta-components/accordion/core/types.ts

@@ -0,0 +1,17 @@
+import type { ReactNode } from "react";
+
+export type AccordionVariant = "separated" | "contained" | "plain";
+
+export type AccordionSize = "sm" | "md" | "lg";
+
+/** Which side of the header the chevron sits on. */
+export type AccordionIconPosition = "start" | "end";
+
+export interface AccordionItemData {
+  value: string;
+  title: ReactNode;
+  /** A second line under the title. */
+  description?: ReactNode;
+  content: ReactNode;
+  disabled?: boolean;
+}

package/source/beta-components/accordion/index.ts

@@ -0,0 +1,8 @@
+export { Accordion } from "./react/Accordion";
+export type { AccordionProps } from "./react/Accordion";
+export { AccordionItem } from "./react/AccordionItem";
+export type { AccordionItemProps } from "./react/AccordionItem";
+export { AccordionContext, useAccordionContext } from "./react/context";
+export type { AccordionContextValue } from "./react/context";
+export type { AccordionItemSlot, AccordionSlot } from "./react/props";
+export * from "./core";

package/source/beta-components/accordion/react/Accordion.tsx

@@ -0,0 +1,133 @@
+"use client";
+
+import {
+  useCallback,
+  useMemo,
+  type CSSProperties,
+  type ReactNode,
+  type Ref,
+} from "react";
+import { useControllableState } from "../../shared/react/useControllableState";
+import { normalizeOpen, toggleOpen } from "../core/open";
+import type {
+  AccordionIconPosition,
+  AccordionItemData,
+  AccordionSize,
+  AccordionVariant,
+} from "../core/types";
+import { AccordionItem } from "./AccordionItem";
+import { AccordionContext, type AccordionContextValue } from "./context";
+import { cx, type AccordionSlot } from "./props";
+
+export interface AccordionProps {
+  /** Open panels, by value (controlled). */
+  value?: string[];
+  defaultValue?: string[];
+  onValueChange?(value: string[]): void;
+  /** Render these panels, or pass `<AccordionItem>` children. */
+  items?: readonly AccordionItemData[];
+  children?: ReactNode;
+  /** Allow more than one panel open at a time. Default false. */
+  multiple?: boolean;
+  /** Allow the open panel to be closed again. Default true. */
+  collapsible?: boolean;
+  /** Default `separated`. */
+  variant?: AccordionVariant;
+  /** Default `md`. */
+  size?: AccordionSize;
+  /** Which side the chevron sits on. Default `end`. */
+  iconPosition?: AccordionIconPosition;
+  className?: string;
+  classNames?: Partial<Record<AccordionSlot, string>>;
+  style?: CSSProperties;
+  ref?: Ref<HTMLDivElement>;
+}
+
+/**
+ * Sections that open one at a time, built on `<details>` and `<summary>`.
+ *
+ * The browser owns the disclosure: the header is focusable, Enter and Space
+ * work, the panel is hidden from search and from the accessibility tree while
+ * closed, and Ctrl+F still finds text inside a closed panel in browsers that
+ * support it. None of that is implemented here.
+ *
+ * What is implemented is the accordion *around* the disclosures — which one is
+ * open, and whether closing the last is allowed — because `<details name>`
+ * alone cannot express a non-collapsible group, and gives no value to store.
+ */
+export function Accordion(props: AccordionProps) {
+  const {
+    ref,
+    value,
+    defaultValue,
+    onValueChange,
+    items,
+    children,
+    multiple = false,
+    collapsible = true,
+    variant = "separated",
+    size = "md",
+    iconPosition = "end",
+    className,
+    classNames,
+    style,
+  } = props;
+
+  const [open, setOpen] = useControllableState<string[]>(value, defaultValue ?? []);
+  const settings = useMemo(() => ({ multiple, collapsible }), [multiple, collapsible]);
+
+  /*
+   * With `items`, the panels are known and the starting value can be trimmed
+   * against them. With children they are not — and asking each item to
+   * register itself would mean either reading a ref while rendering or a
+   * second render pass on mount, for the sake of dropping a value that already
+   * matches nothing and shows nothing.
+   *
+   * The one thing that needs the list is opening a panel in a non-collapsible
+   * accordion that starts with none open, so give that case a `defaultValue`.
+   */
+  const effective = useMemo(
+    () => normalizeOpen(open, items ? items.map((item) => item.value) : open, settings),
+    [open, items, settings],
+  );
+
+  const toggle = useCallback(
+    (item: string) => {
+      const next = toggleOpen(effective, item, settings);
+      setOpen(next);
+      onValueChange?.(next);
+    },
+    [effective, settings, setOpen, onValueChange],
+  );
+
+  const context = useMemo<AccordionContextValue>(
+    () => ({ open: effective, toggle, size, variant, iconPosition }),
+    [effective, toggle, size, variant, iconPosition],
+  );
+
+  return (
+    <div
+      ref={ref}
+      className={cx("ac-root", classNames?.root, className)}
+      style={style}
+      data-variant={variant}
+      data-size={size}
+    >
+      <AccordionContext value={context}>
+        {items
+          ? items.map((item) => (
+              <AccordionItem
+                key={item.value}
+                value={item.value}
+                title={item.title}
+                description={item.description}
+                disabled={item.disabled}
+              >
+                {item.content}
+              </AccordionItem>
+            ))
+          : children}
+      </AccordionContext>
+    </div>
+  );
+}

package/source/beta-components/accordion/react/AccordionItem.tsx

@@ -0,0 +1,120 @@
+"use client";
+
+import {
+  useId,
+  type CSSProperties,
+  type MouseEvent,
+  type ReactNode,
+  type Ref,
+} from "react";
+import { ChevronDownIcon } from "../../shared/react/icons";
+import { useAccordionContext } from "./context";
+import { cx, type AccordionItemSlot } from "./props";
+
+export interface AccordionItemProps {
+  /** Identifies the panel in the accordion's value. */
+  value: string;
+  title: ReactNode;
+  /** A second line under the title. */
+  description?: ReactNode;
+  children?: ReactNode;
+  /** Something at the end of the header: a badge, a count. */
+  meta?: ReactNode;
+  /** Replaces the chevron. */
+  icon?: ReactNode;
+  disabled?: boolean;
+  className?: string;
+  classNames?: Partial<Record<AccordionItemSlot, string>>;
+  style?: CSSProperties;
+  ref?: Ref<HTMLDetailsElement>;
+}
+
+/**
+ * One section. A `<details>` whose open state the accordion owns, so the group
+ * can close the others and refuse to close the last one.
+ */
+export function AccordionItem(props: AccordionItemProps) {
+  const {
+    ref,
+    value,
+    title,
+    description,
+    children,
+    meta,
+    icon,
+    disabled = false,
+    className,
+    classNames,
+    style,
+  } = props;
+
+  const context = useAccordionContext("AccordionItem");
+  const id = useId();
+  const open = context.open.includes(value);
+
+  const onClick = (event: MouseEvent<HTMLElement>) => {
+    // The accordion decides; letting the browser toggle as well would fight it.
+    event.preventDefault();
+    if (!disabled) context.toggle(value);
+  };
+
+  return (
+    <details
+      ref={ref}
+      className={cx("ac-item", classNames?.root, className)}
+      style={style}
+      open={open}
+      data-disabled={disabled || undefined}
+    >
+      <summary
+        id={`${id}-header`}
+        className={cx("ac-header", classNames?.header)}
+        /*
+         * An explicit button role, because a bare <summary> is exposed as a
+         * group in Chromium and `aria-expanded` on it is ignored — so the one
+         * thing a screen reader most needs to know, whether the section is
+         * open, never gets announced. The role changes nothing about the
+         * keyboard: Enter and Space still come from <details> itself.
+         */
+        role="button"
+        aria-expanded={open}
+        aria-controls={`${id}-content`}
+        // A disabled section is marked rather than removed from the tab order:
+        // the heading of something you cannot open is still worth reading, and
+        // dropping it loses it silently.
+        aria-disabled={disabled || undefined}
+        onClick={onClick}
+      >
+        {context.iconPosition === "start" && (
+          <span className={cx("ac-icon", classNames?.icon)} aria-hidden="true">
+            {icon ?? <ChevronDownIcon />}
+          </span>
+        )}
+
+        <span className="ac-heading">
+          <span className={cx("ac-title", classNames?.title)}>{title}</span>
+          {description && (
+            <span className={cx("ac-description", classNames?.description)}>{description}</span>
+          )}
+        </span>
+
+        {meta && <span className="ac-meta">{meta}</span>}
+
+        {context.iconPosition === "end" && (
+          <span className={cx("ac-icon", classNames?.icon)} aria-hidden="true">
+            {icon ?? <ChevronDownIcon />}
+          </span>
+        )}
+      </summary>
+
+      <div
+        id={`${id}-content`}
+        className={cx("ac-content", classNames?.content)}
+        role="region"
+        aria-labelledby={`${id}-header`}
+      >
+        <div className={cx("ac-body", classNames?.body)}>{children}</div>
+      </div>
+    </details>
+  );
+}

package/source/beta-components/accordion/react/context.ts

@@ -0,0 +1,20 @@
+"use client";
+
+import { createContext, use } from "react";
+import type { AccordionIconPosition, AccordionSize, AccordionVariant } from "../core/types";
+
+export interface AccordionContextValue {
+  open: readonly string[];
+  toggle(value: string): void;
+  size: AccordionSize;
+  variant: AccordionVariant;
+  iconPosition: AccordionIconPosition;
+}
+
+export const AccordionContext = createContext<AccordionContextValue | null>(null);
+
+export function useAccordionContext(component: string): AccordionContextValue {
+  const context = use(AccordionContext);
+  if (!context) throw new Error(`<${component}> must be used inside an <Accordion>.`);
+  return context;
+}

package/source/beta-components/accordion/react/props.ts

@@ -0,0 +1,13 @@
+export type AccordionSlot = "root";
+
+export type AccordionItemSlot =
+  | "root"
+  | "header"
+  | "title"
+  | "description"
+  | "icon"
+  | "content"
+  | "body";
+
+// Shared with every other component, so class handling cannot drift.
+export { cx } from "../../shared/core/cx";