@carissa-io/components-list 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,75 @@
-# Temporary Holding Version
+# @carissa-io/components-list
 
-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.
+List: `List` and `ListItem`. A `ul` or `ol` of rows with leading and trailing slots, secondary text, link and button rows and
+three variants. A React component set, SCSS-themed, with no other dependency.
+
+```bash
+npm i @carissa-io/components-list
+```
+
+## Use
+
+```jsx
+import { List, ListItem } from '@carissa-io/components-list'
+
+<List variant="divided" aria-label={t('recent_files')}>
+    <ListItem leading={<FileIcon />} description={t('edited_today')} trailing={<Badge>3</Badge>} href="/files/1" selected>
+        Report.pdf
+    </ListItem>
+    <ListItem leading={<FileIcon />} interactive onClick={open}>
+        Notes.txt
+    </ListItem>
+    <ListItem>Read-only row</ListItem>
+</List>
+```
+
+| Part | Prop | |
+|---|---|---|
+| `List` | `as` | `ul` (default) or `ol`; anything else falls back to `ul` |
+| | `variant` | `plain` (default), `bordered` (outer border) or `divided` (a divider between items); anything else falls back to `plain` |
+| | `size` | `sm`, `md` (default) or `lg`, the row padding and font size; anything else falls back to `md` |
+| `ListItem` | `leading`, `trailing` | slots before and after the text (an icon, an avatar, an action, a value) |
+| | `description` | secondary text under the main text |
+| | `href` | renders a link row (`<a>`) |
+| | `interactive` | without `href`, renders a `button` row; `onClick` etc. go to it |
+| | `selected` | `aria-current="true"` on the row element and the `c-list__item--selected` class |
+| | `disabled` | disables a button row; a link row gets `aria-disabled="true"` and loses its `href` |
+| | `as` | the item's own tag: `li` (default) or `div`; anything else falls back to `li` |
+
+`className` is appended on `List` and to the `li` of an item; unknown props go to the list on `List` and to the row element
+(link, button or div) on `ListItem`. `href` wins over `interactive`.
+
+## Accessibility
+
+A real list (`ul`/`ol` with `li`), so screen readers announce the number of items. Link and button rows are native
+elements: Tab reaches them, Enter follows a link, Enter and Space press a button. A plain row is not a tab stop. `selected` uses
+`aria-current`, which suits navigation and "current item" lists; for a multi-select list the app puts its own checkbox in the
+`leading` slot. Give the list an accessible name (`aria-label`) when it is not introduced by a heading.
+
+## Style
+
+```scss
+@use '@carissa-io/components-list/scss' with (
+    $c-list-item-padding-x: 1rem,
+    $c-list-border-color: #ddd
+);
+```
+
+Classes: `c-list` (`--plain`, `--bordered`, `--divided`, `--sm`, `--md`, `--lg`), `c-list__item` (`--interactive`,
+`--selected`, `--disabled`), `c-list__row`, `c-list__leading`, `c-list__body`, `c-list__text`, `c-list__description` and
+`c-list__trailing`. 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-list-item-padding-x`, `$c-list-item-padding-y` | `0.75rem`, `0.5rem` |
+| `$c-list-item-padding-y-sm`, `$c-list-item-padding-y-lg` | `0.25rem`, `0.75rem` |
+| `$c-list-item-gap` | `0.75rem` |
+| `$c-list-font-size`, `$c-list-font-size-sm`, `$c-list-font-size-lg` | `1rem`, `0.875rem`, `1.125rem` |
+| `$c-list-ordered-indent` | `1.5rem` |
+| `$c-list-description-color`, `$c-list-description-font-size` | `rgb(0 0 0 / 0.6)`, `0.875rem` |
+| `$c-list-border-width`, `$c-list-border-color`, `$c-list-radius` | `1px`, `rgb(0 0 0 / 0.15)`, `0.375rem` |
+| `$c-list-item-background-hover`, `$c-list-item-background-selected` | `rgb(0 0 0 / 0.04)`, `rgb(0 0 0 / 0.08)` |
+| `$c-list-item-color-selected`, `$c-list-item-disabled-opacity` | `inherit`, `0.5` |
+| `$c-list-focus-outline`, `$c-list-focus-outline-offset` | `2px solid currentColor`, `-2px` |
+| `$c-list-transition-duration` | `0.15s` |

package/dist/index.js

@@ -0,0 +1,68 @@
+// src/List.jsx
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+var TAGS = ["ul", "ol"];
+var VARIANTS = ["plain", "bordered", "divided"];
+var SIZES = ["sm", "md", "lg"];
+var ITEM_TAGS = ["li", "div"];
+var has = (node) => node !== void 0 && node !== null && node !== false && node !== "";
+var join = (...parts) => parts.filter(Boolean).join(" ");
+function List({ as = "ul", variant = "plain", size = "md", className = "", children, ...rest }) {
+  const Tag = TAGS.includes(as) ? as : "ul";
+  const safe_variant = VARIANTS.includes(variant) ? variant : "plain";
+  const safe_size = SIZES.includes(size) ? size : "md";
+  return /* @__PURE__ */ jsx(Tag, { ...rest, className: join("c-list", `c-list--${safe_variant}`, `c-list--${safe_size}`, className), children });
+}
+function ListItem({
+  leading,
+  trailing,
+  description,
+  interactive = false,
+  href,
+  as = "li",
+  selected = false,
+  disabled = false,
+  className = "",
+  children,
+  ...rest
+}) {
+  const Tag = ITEM_TAGS.includes(as) ? as : "li";
+  const is_link = has(href);
+  const is_button = !is_link && interactive === true;
+  const is_selected = selected === true;
+  const is_disabled = disabled === true;
+  const content = /* @__PURE__ */ jsxs(Fragment, { children: [
+    has(leading) ? /* @__PURE__ */ jsx("span", { className: "c-list__leading", children: leading }) : null,
+    /* @__PURE__ */ jsxs("span", { className: "c-list__body", children: [
+      /* @__PURE__ */ jsx("span", { className: "c-list__text", children }),
+      has(description) ? /* @__PURE__ */ jsx("span", { className: "c-list__description", children: description }) : null
+    ] }),
+    has(trailing) ? /* @__PURE__ */ jsx("span", { className: "c-list__trailing", children: trailing }) : null
+  ] });
+  const row_class = "c-list__row";
+  const row_props = { ...rest, "aria-current": is_selected ? "true" : void 0 };
+  let row;
+  if (is_link) {
+    row = is_disabled ? /* @__PURE__ */ jsx("a", { ...row_props, role: "link", "aria-disabled": "true", className: row_class, children: content }) : /* @__PURE__ */ jsx("a", { ...row_props, href, className: row_class, children: content });
+  } else if (is_button) {
+    row = /* @__PURE__ */ jsx("button", { type: "button", ...row_props, disabled: is_disabled, className: row_class, children: content });
+  } else {
+    row = /* @__PURE__ */ jsx("div", { ...row_props, className: row_class, children: content });
+  }
+  return /* @__PURE__ */ jsx(
+    Tag,
+    {
+      className: join(
+        "c-list__item",
+        (is_link || is_button) && "c-list__item--interactive",
+        is_selected && "c-list__item--selected",
+        is_disabled && "c-list__item--disabled",
+        className
+      ),
+      children: row
+    }
+  );
+}
+export {
+  List,
+  ListItem
+};

package/package.json

@@ -1,6 +1,56 @@
 {
   "name": "@carissa-io/components-list",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Carissa UI: list with leading and trailing slots, link rows and variants 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-list.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/_list.scss

@@ -0,0 +1,115 @@
+@use 'variables' as *;
+
+.c-list {
+    box-sizing: border-box;
+    padding: 0;
+    margin: 0;
+    font-size: $c-list-font-size;
+    list-style: none;
+}
+
+ol.c-list {
+    padding-inline-start: $c-list-ordered-indent;
+    list-style: decimal;
+}
+
+.c-list--sm {
+    font-size: $c-list-font-size-sm;
+}
+
+.c-list--lg {
+    font-size: $c-list-font-size-lg;
+}
+
+.c-list--bordered {
+    overflow: hidden;
+    border: $c-list-border-width solid $c-list-border-color;
+    border-radius: $c-list-radius;
+}
+
+.c-list--bordered > .c-list__item + .c-list__item,
+.c-list--divided > .c-list__item + .c-list__item {
+    border-top: $c-list-border-width solid $c-list-border-color;
+}
+
+.c-list__item {
+    display: list-item;
+    padding: 0;
+    margin: 0;
+
+    &--selected {
+        color: $c-list-item-color-selected;
+        background: $c-list-item-background-selected;
+    }
+
+    &--disabled {
+        cursor: not-allowed;
+        opacity: $c-list-item-disabled-opacity;
+    }
+}
+
+.c-list__row {
+    box-sizing: border-box;
+    display: flex;
+    gap: $c-list-item-gap;
+    align-items: center;
+    width: 100%;
+    padding: $c-list-item-padding-y $c-list-item-padding-x;
+    font: inherit;
+    color: inherit;
+    text-align: start;
+    text-decoration: none;
+    background: transparent;
+    border: 0;
+}
+
+.c-list--sm .c-list__row {
+    padding-block: $c-list-item-padding-y-sm;
+}
+
+.c-list--lg .c-list__row {
+    padding-block: $c-list-item-padding-y-lg;
+}
+
+.c-list__item--interactive > .c-list__row {
+    cursor: pointer;
+    transition: background-color $c-list-transition-duration ease-out;
+
+    &:hover {
+        background: $c-list-item-background-hover;
+    }
+
+    &:focus-visible {
+        outline: $c-list-focus-outline;
+        outline-offset: $c-list-focus-outline-offset;
+    }
+}
+
+.c-list__item--disabled > .c-list__row {
+    pointer-events: none;
+}
+
+.c-list__leading,
+.c-list__trailing {
+    display: inline-flex;
+    flex: none;
+    align-items: center;
+}
+
+.c-list__body {
+    display: flex;
+    flex: 1;
+    flex-direction: column;
+    min-width: 0;
+}
+
+.c-list__description {
+    font-size: $c-list-description-font-size;
+    color: $c-list-description-color;
+}
+
+@media (prefers-reduced-motion: reduce) {
+    .c-list__item--interactive > .c-list__row {
+        transition: none;
+    }
+}

package/scss/_variables.scss

@@ -0,0 +1,38 @@
+// Every value is `!default`: set it before the first @use / through `with (...)` and it wins.
+//
+//   @use '@carissa-io/components-list/scss' with ($c-list-item-padding-x: 1rem, $c-list-border-color: #ddd);
+//
+// The defaults are neutral (no fills, thin borders), so the component works without a theme.
+
+// Item
+$c-list-item-padding-x: 0.75rem !default;
+$c-list-item-padding-y: 0.5rem !default;
+$c-list-item-padding-y-sm: 0.25rem !default;
+$c-list-item-padding-y-lg: 0.75rem !default;
+$c-list-item-gap: 0.75rem !default; // between leading, body and trailing
+$c-list-font-size: 1rem !default;
+$c-list-font-size-sm: 0.875rem !default;
+$c-list-font-size-lg: 1.125rem !default;
+$c-list-ordered-indent: 1.5rem !default; // the number column of an `ol`
+
+// Secondary text
+$c-list-description-color: rgb(0 0 0 / 0.6) !default;
+$c-list-description-font-size: 0.875rem !default;
+
+// Borders and variants
+$c-list-border-width: 1px !default;
+$c-list-border-color: rgb(0 0 0 / 0.15) !default;
+$c-list-radius: 0.375rem !default;
+
+// States
+$c-list-item-background-hover: rgb(0 0 0 / 0.04) !default;
+$c-list-item-background-selected: rgb(0 0 0 / 0.08) !default;
+$c-list-item-color-selected: inherit !default;
+$c-list-item-disabled-opacity: 0.5 !default;
+
+// Focus
+$c-list-focus-outline: 2px solid currentColor !default;
+$c-list-focus-outline-offset: -2px !default;
+
+// Motion
+$c-list-transition-duration: 0.15s !default;

package/scss/index.scss

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