@carissa-io/components-accordion 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,78 @@
-# Temporary Holding Version
+# @carissa-io/components-accordion
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Accordion: `Accordion` and `AccordionItem`, following the WAI-ARIA accordion pattern. A React component set, SCSS-themed,
+with no other dependency (the chevron is drawn in CSS).
+
+```bash
+npm i @carissa-io/components-accordion
+```
+
+## Use
+
+```jsx
+import { Accordion, AccordionItem } from '@carissa-io/components-accordion'
+
+<Accordion type="single" default_value="shipping" on_change={(value) => track(value)}>
+    <AccordionItem value="shipping" title={t('shipping')}>...</AccordionItem>
+    <AccordionItem value="returns" title={t('returns')} title_level={2}>...</AccordionItem>
+    <AccordionItem value="warranty" title={t('warranty')} disabled>...</AccordionItem>
+</Accordion>
+```
+
+Uncontrolled with `default_value` or controlled with `value` and `on_change(value)`. `value` is a string in `single` mode
+(an empty string means none open) and an array in `multiple` mode; `on_change` receives the same shape.
+
+| Part | Prop | |
+|---|---|---|
+| `Accordion` | `type` | `single` (default, one open item) or `multiple`; anything else falls back to `single` |
+| | `value` | the open item (`single`) or items (`multiple`), controlled |
+| | `default_value` | the same, when uncontrolled |
+| | `on_change` | `on_change(value)` when the user toggles an item (also when controlled) |
+| | `collapsible` | default `true`; in `single` mode, `false` keeps one item open once opened (`multiple` always closes) |
+| `AccordionItem` | `value` | identifies the item in the accordion's value |
+| | `title` | the content of the header button |
+| | `title_level` | the document level of the heading around the button, `1` to `6`, default `3` |
+| | `disabled` | cannot be toggled, skipped by the keyboard |
+
+Children of `AccordionItem` are its region. They stay mounted while it is closed (the region is `hidden`), so their state
+survives. `className` is appended and unknown props go to the root `div` of each part.
+
+## Accessibility
+
+Each item is a heading (`h<title_level>`) holding a `button` with `aria-expanded` and `aria-controls`, and a `div role="region"`
+with `aria-labelledby` pointing to the button, `hidden` when closed. The ids come from `useId` plus the value.
+
+| Key | Action |
+|---|---|
+| Enter / Space | toggle the focused header (the native button) |
+| Arrow Down / Up | focus the next / previous enabled header, wrapping at the ends |
+| Home / End | focus the first / last enabled header |
+
+## Style
+
+```scss
+@use '@carissa-io/components-accordion/scss' with (
+    $c-accordion-radius: 0.5rem,
+    $c-accordion-header-background-hover: #f1f3f5
+);
+```
+
+Classes: `c-accordion`, `c-accordion__item` (`--open`, `--disabled`), `c-accordion__heading`, `c-accordion__trigger`,
+`c-accordion__title`, `c-accordion__region` and `c-accordion__content`. The chevron is `c-accordion__trigger::after`, rotated by
+`aria-expanded`; there is no icon dependency. Every variable is `!default` (see [scss/_variables.scss](scss/_variables.scss));
+the defaults are neutral, so the component works without a theme. Transitions are disabled with `prefers-reduced-motion`.
+
+| Variable | Default |
+|---|---|
+| `$c-accordion-border-width`, `$c-accordion-border-color`, `$c-accordion-radius` | `1px`, `rgb(0 0 0 / 0.15)`, `0` |
+| `$c-accordion-header-padding-x`, `$c-accordion-header-padding-y` | `1rem`, `0.75rem` |
+| `$c-accordion-header-font-size`, `$c-accordion-header-font-weight` | `1rem`, `500` |
+| `$c-accordion-header-color`, `$c-accordion-header-background` | `inherit`, `transparent` |
+| `$c-accordion-header-background-hover` | `rgb(0 0 0 / 0.04)` |
+| `$c-accordion-header-color-open`, `$c-accordion-header-background-open` | `inherit`, `transparent` |
+| `$c-accordion-chevron-size`, `$c-accordion-chevron-thickness`, `$c-accordion-chevron-color` | `0.5rem`, `2px`, `currentColor` |
+| `$c-accordion-chevron-rotation-open` | `180deg` |
+| `$c-accordion-content-padding-x`, `$c-accordion-content-padding-y` | `1rem`, `0.75rem` |
+| `$c-accordion-focus-outline`, `$c-accordion-focus-outline-offset` | `2px solid currentColor`, `-2px` |
+| `$c-accordion-disabled-opacity` | `0.5` |
+| `$c-accordion-transition-duration` | `0.15s` |

package/dist/index.js

@@ -0,0 +1,93 @@
+// src/Accordion.jsx
+import { createContext, useContext, useId, useState } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+var TYPES = ["single", "multiple"];
+var LEVELS = [1, 2, 3, 4, 5, 6];
+var AccordionContext = createContext(null);
+var join = (...parts) => parts.filter(Boolean).join(" ");
+var slug = (value) => String(value).replace(/\s+/g, "_");
+function to_list(type, value) {
+  if (type === "multiple") return Array.isArray(value) ? value : value === void 0 || value === null || value === "" ? [] : [value];
+  if (Array.isArray(value)) return value.length ? [value[0]] : [];
+  return value === void 0 || value === null || value === "" ? [] : [value];
+}
+function Accordion({
+  type = "single",
+  value,
+  default_value,
+  on_change,
+  collapsible = true,
+  className = "",
+  onKeyDown,
+  children,
+  ...rest
+}) {
+  const base_id = useId();
+  const safe_type = TYPES.includes(type) ? type : "single";
+  const [inner, setInner] = useState(default_value);
+  const controlled = value !== void 0;
+  const open = to_list(safe_type, controlled ? value : inner);
+  const toggle = (item) => {
+    const is_open = open.includes(item);
+    let next;
+    if (safe_type === "multiple") {
+      next = is_open ? open.filter((entry) => entry !== item) : [...open, item];
+    } else if (is_open) {
+      if (!collapsible) return;
+      next = "";
+    } else {
+      next = item;
+    }
+    if (!controlled) setInner(next);
+    if (on_change) on_change(next);
+  };
+  const handle_key_down = (event) => {
+    if (onKeyDown) onKeyDown(event);
+    if (event.defaultPrevented) return;
+    const origin = event.target.closest?.(".c-accordion__trigger");
+    if (!origin || origin.closest(".c-accordion") !== event.currentTarget) return;
+    const triggers = Array.from(event.currentTarget.querySelectorAll(".c-accordion__trigger")).filter(
+      (trigger) => !trigger.disabled && trigger.closest(".c-accordion") === event.currentTarget
+    );
+    const index = triggers.indexOf(origin);
+    if (index === -1) return;
+    let target;
+    if (event.key === "ArrowDown") target = triggers[(index + 1) % triggers.length];
+    else if (event.key === "ArrowUp") target = triggers[(index - 1 + triggers.length) % triggers.length];
+    else if (event.key === "Home") target = triggers[0];
+    else if (event.key === "End") target = triggers[triggers.length - 1];
+    else return;
+    event.preventDefault();
+    target.focus();
+  };
+  return /* @__PURE__ */ jsx(AccordionContext.Provider, { value: { base_id, open, toggle }, children: /* @__PURE__ */ jsx("div", { ...rest, className: join("c-accordion", className), onKeyDown: handle_key_down, children }) });
+}
+function AccordionItem({ value, title, title_level = 3, disabled = false, className = "", children, ...rest }) {
+  const context = useContext(AccordionContext);
+  if (!context) throw new Error("AccordionItem must be rendered inside Accordion");
+  const { base_id, open, toggle } = context;
+  const is_open = open.includes(value);
+  const Heading = `h${LEVELS.includes(Number(title_level)) ? Number(title_level) : 3}`;
+  const trigger_id = `${base_id}-trigger-${slug(value)}`;
+  const region_id = `${base_id}-region-${slug(value)}`;
+  return /* @__PURE__ */ jsxs("div", { ...rest, className: join("c-accordion__item", is_open && "c-accordion__item--open", disabled && "c-accordion__item--disabled", className), children: [
+    /* @__PURE__ */ jsx(Heading, { className: "c-accordion__heading", children: /* @__PURE__ */ jsx(
+      "button",
+      {
+        type: "button",
+        id: trigger_id,
+        className: "c-accordion__trigger",
+        "aria-expanded": is_open,
+        "aria-controls": region_id,
+        disabled,
+        onClick: () => toggle(value),
+        children: /* @__PURE__ */ jsx("span", { className: "c-accordion__title", children: title })
+      }
+    ) }),
+    /* @__PURE__ */ jsx("div", { id: region_id, role: "region", "aria-labelledby": trigger_id, hidden: !is_open, className: "c-accordion__region", children: /* @__PURE__ */ jsx("div", { className: "c-accordion__content", children }) })
+  ] });
+}
+export {
+  Accordion,
+  AccordionItem
+};

package/package.json

@@ -1,6 +1,56 @@
 {
   "name": "@carissa-io/components-accordion",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Carissa UI: accessible accordion of collapsible sections as React components with SCSS variables",
+  "type": "module",
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "scss",
+    "THIRD-PARTY-NOTICES"
+  ],
+  "exports": {
+    ".": "./dist/index.js",
+    "./scss": "./scss/index.scss",
+    "./scss/*": "./scss/*"
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "esbuild src/index.js --bundle --packages=external --format=esm --jsx=automatic --outfile=dist/index.js",
+    "test": "vitest run",
+    "lint": "eslint .",
+    "prepublishOnly": "node -e \"if (!process.env.GITHUB_ACTIONS) { console.error('Refusing to publish outside GitHub Actions CI: commit and push to main instead.'); process.exit(1); }\" && npm run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/carissa-io/components-accordion.git"
+  },
+  "license": "UNLICENSED",
+  "engines": {
+    "node": ">=24"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@testing-library/jest-dom": "^7.0.1",
+    "@testing-library/react": "^16.3.3",
+    "@testing-library/user-event": "^14.6.7",
+    "@vitejs/plugin-react": "^6.1.1",
+    "esbuild": "^0.28.0",
+    "eslint": "^10.12.0",
+    "eslint-plugin-react-hooks": "^7.1.1",
+    "globals": "^17.13.0",
+    "jsdom": "^29.1.1",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
+    "sass-embedded": "^1.105.1",
+    "vite": "^8.3.2",
+    "vitest": "^4.1.11"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  }
+}

package/scss/_accordion.scss

@@ -0,0 +1,99 @@
+@use 'variables' as *;
+
+.c-accordion {
+    box-sizing: border-box;
+    border: $c-accordion-border-width solid $c-accordion-border-color;
+    border-radius: $c-accordion-radius;
+}
+
+.c-accordion__item {
+    &:not(:first-child) {
+        border-top: $c-accordion-border-width solid $c-accordion-border-color;
+    }
+
+    &:first-child > .c-accordion__heading .c-accordion__trigger {
+        border-top-left-radius: $c-accordion-radius;
+        border-top-right-radius: $c-accordion-radius;
+    }
+
+    &:last-child:not(.c-accordion__item--open) > .c-accordion__heading .c-accordion__trigger {
+        border-bottom-right-radius: $c-accordion-radius;
+        border-bottom-left-radius: $c-accordion-radius;
+    }
+}
+
+.c-accordion__heading {
+    margin: 0;
+    font: inherit;
+}
+
+.c-accordion__trigger {
+    box-sizing: border-box;
+    display: flex;
+    gap: 1rem;
+    align-items: center;
+    justify-content: space-between;
+    width: 100%;
+    padding: $c-accordion-header-padding-y $c-accordion-header-padding-x;
+    font: inherit;
+    font-size: $c-accordion-header-font-size;
+    font-weight: $c-accordion-header-font-weight;
+    line-height: 1.5;
+    color: $c-accordion-header-color;
+    text-align: start;
+    cursor: pointer;
+    background: $c-accordion-header-background;
+    border: 0;
+    transition: background-color $c-accordion-transition-duration ease-out;
+
+    // The chevron: a rotated corner of a box, so no icon dependency. It follows aria-expanded.
+    &::after {
+        flex: none;
+        box-sizing: border-box;
+        width: $c-accordion-chevron-size;
+        height: $c-accordion-chevron-size;
+        content: '';
+        border-right: $c-accordion-chevron-thickness solid $c-accordion-chevron-color;
+        border-bottom: $c-accordion-chevron-thickness solid $c-accordion-chevron-color;
+        transform: translateY(-25%) rotate(45deg);
+        transition: transform $c-accordion-transition-duration ease-out;
+    }
+
+    &[aria-expanded='true'] {
+        color: $c-accordion-header-color-open;
+        background: $c-accordion-header-background-open;
+
+        &::after {
+            transform: translateY(25%) rotate(45deg + $c-accordion-chevron-rotation-open);
+        }
+    }
+
+    &:hover:not(:disabled) {
+        background: $c-accordion-header-background-hover;
+    }
+
+    &:focus-visible {
+        outline: $c-accordion-focus-outline;
+        outline-offset: $c-accordion-focus-outline-offset;
+    }
+
+    &:disabled {
+        cursor: not-allowed;
+        opacity: $c-accordion-disabled-opacity;
+    }
+}
+
+.c-accordion__region[hidden] {
+    display: none;
+}
+
+.c-accordion__content {
+    padding: $c-accordion-content-padding-y $c-accordion-content-padding-x;
+}
+
+@media (prefers-reduced-motion: reduce) {
+    .c-accordion__trigger,
+    .c-accordion__trigger::after {
+        transition: none;
+    }
+}

package/scss/_variables.scss

@@ -0,0 +1,39 @@
+// Every value is `!default`: set it before the first @use / through `with (...)` and it wins.
+//
+//   @use '@carissa-io/components-accordion/scss' with ($c-accordion-header-background-hover: #f1f3f5, $c-accordion-radius: 0.5rem);
+//
+// The defaults are neutral (bordered sections with a CSS chevron), so the component works without a theme.
+
+// Box
+$c-accordion-border-width: 1px !default;
+$c-accordion-border-color: rgb(0 0 0 / 0.15) !default;
+$c-accordion-radius: 0 !default;
+
+// Header
+$c-accordion-header-padding-x: 1rem !default;
+$c-accordion-header-padding-y: 0.75rem !default;
+$c-accordion-header-font-size: 1rem !default;
+$c-accordion-header-font-weight: 500 !default;
+$c-accordion-header-color: inherit !default;
+$c-accordion-header-background: transparent !default;
+$c-accordion-header-background-hover: rgb(0 0 0 / 0.04) !default;
+$c-accordion-header-color-open: inherit !default;
+$c-accordion-header-background-open: transparent !default;
+
+// Chevron (drawn with CSS, rotated while open)
+$c-accordion-chevron-size: 0.5rem !default;
+$c-accordion-chevron-thickness: 2px !default;
+$c-accordion-chevron-color: currentColor !default;
+$c-accordion-chevron-rotation-open: 180deg !default;
+
+// Content
+$c-accordion-content-padding-x: 1rem !default;
+$c-accordion-content-padding-y: 0.75rem !default;
+
+// Focus and disabled
+$c-accordion-focus-outline: 2px solid currentColor !default;
+$c-accordion-focus-outline-offset: -2px !default;
+$c-accordion-disabled-opacity: 0.5 !default;
+
+// Motion
+$c-accordion-transition-duration: 0.15s !default;

package/scss/index.scss

@@ -0,0 +1,2 @@
+@forward 'variables';
+@use 'accordion';