@carissa-io/webkit-footer 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,104 @@
-# Temporary Holding Version
+# @carissa-io/webkit-footer
 
-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.
+The end of a public website's pages: an index of the site (columns of links, each with a heading) and a legal row under a
+1px rule. A layout with slots, not a template: no newsletter form, no back-to-top, no icons or arrows, no gradient, no
+default shadow and no motion. A React component, SCSS-themed, safe on the server, with no runtime dependency.
+
+**The component has no strings of its own.** Every text and link comes from the site. The look comes from the theme's
+second stylesheet, `@carissa-io/theme-default/webkit.css`, which apps do not load.
+
+```bash
+npm i @carissa-io/webkit-footer
+```
+
+## Use
+
+```jsx
+import { Footer } from '@carissa-io/webkit-footer'
+
+<Footer
+    as="footer"
+    brand={<Logo />}
+    description={t('footer_description')}
+    nav_label={t('footer_nav_label')}
+    columns={[
+        { id: 'product', title: t('product'), links: [{ href: '/passkeys', label: t('passkeys') }, { href: '/pricing', label: t('pricing') }] },
+        { id: 'company', title: t('company'), links: [{ href: '/about', label: t('about') }] },
+    ]}
+    legal={
+        <>
+            <small>{t('copyright')}</small>
+            <a href="/privacy">{t('privacy')}</a>
+        </>
+    }
+/>
+```
+
+| Prop | |
+|---|---|
+| `brand` | a node: the logo or the name, first in the brand block |
+| `description` | a short paragraph under the brand; its measure is limited by `$c-footer-description-max-width` |
+| `columns` | `[{ id, title, links: [{ href, label }] }]`; not an array renders no index |
+| `title_level` | heading level of the column titles, `1` to `6`, default `2`; anything else falls back to `2` |
+| `nav_label` | the accessible name of the index; a non-empty string wraps the index in `<nav aria-label>`, anything else renders a plain `div` |
+| `legal` | a node for the copyright and the legal links, in the second row |
+| `social` | an optional node in the second row, after `legal` |
+| `as` | the root tag, `div` by default; a value that is not a tag name falls back to `div` |
+| `className`, `id`, ... | `className` is appended; unknown props go to the root |
+
+Invalid input falls back instead of failing: columns that are not objects or have no usable links are skipped, links without
+a non-empty `href` or without a `label` are skipped, a column without a `title` renders its list without a heading. An empty
+slot (`undefined`, `null`, `false`, `''`) renders nothing, so a footer with only `legal` is valid.
+
+### Layout
+
+Below `$c-footer-breakpoint` (40rem) everything is one column: brand, then the index, then the legal row. From there, when
+both a brand block and an index exist, they sit side by side. The index is an auto-fit grid whose columns are at least
+`$c-footer-column-min-width` wide, so it adds or drops columns with the space it has and never overflows. The legal row
+wraps. The DOM order is always brand, index, legal row, and nothing reorders it with CSS.
+
+## Accessibility
+
+- **Landmarks.** The root is a `div` because the page frame (a site shell) usually owns the `footer` landmark. Used on its
+  own, pass `as="footer"`: a `footer` that is a descendant of `main` or `article` is not a `contentinfo` landmark, so keep
+  it outside them.
+- **Navigation.** Pass `nav_label` (translated by the site) so the index is a named `navigation` landmark ("Site map",
+  "Footer"). A page with another `nav` (the header) needs the names to differ. Without `nav_label` no landmark is created.
+- **Lists and headings.** Each column is a `ul` labelled by its heading, so a screen reader announces the group and its
+  size. Set `title_level` to fit the page outline (the default is `h2`; use a lower level if the footer sits inside a section).
+- **Focus.** Links are plain `<a>`; the focus ring is the theme's and the footer styles no `outline`. Link text is the label
+  you pass: make it descriptive on its own.
+
+## Style
+
+```scss
+@use '@carissa-io/webkit-footer/scss' with (
+    $c-footer-column-min-width: 12rem,
+    $c-footer-description-max-width: 36ch
+);
+```
+
+Classes: `c-footer`, `c-footer__inner`, `c-footer__top` (`--split`), `c-footer__brand`, `c-footer__logo`,
+`c-footer__description`, `c-footer__nav`, `c-footer__column`, `c-footer__title`, `c-footer__list`, `c-footer__item`,
+`c-footer__link`, `c-footer__legal-row`, `c-footer__legal`, `c-footer__social`. Every variable is `!default` (see
+[scss/_variables.scss](scss/_variables.scss)). The defaults are neutral: `inherit`, `transparent`, a `currentcolor` rule, no
+shadow, no gradient, no transition; the theme supplies sizes from its type scale and colours as `var(--c-*)`.
+
+| Variable | Default |
+|---|---|
+| `$c-footer-font-family`, `-color`, `-background` | `inherit`, `inherit`, `transparent` |
+| `$c-footer-max-width` | `80rem` (inner block, centred) |
+| `$c-footer-padding-block` | `3rem` |
+| `$c-footer-padding-inline`, `-inline-wide`, `-padding-breakpoint` | `1rem`, `2rem`, `40rem` |
+| `$c-footer-breakpoint` | `40rem` (brand and index side by side from here) |
+| `$c-footer-top-columns`, `-top-gap` | `minmax(0, 1fr) minmax(0, 2fr)`, `3rem` |
+| `$c-footer-column-min-width`, `-column-gap` | `10rem`, `2rem` |
+| `$c-footer-brand-gap` | `1rem` |
+| `$c-footer-description-font-size`, `-line-height`, `-color`, `-max-width` | `inherit`, `1.5`, `inherit`, `40ch` |
+| `$c-footer-title-font-size`, `-font-weight`, `-letter-spacing`, `-text-transform`, `-color`, `-margin-bottom` | `inherit`, `700`, `normal`, `none`, `inherit`, `1rem` |
+| `$c-footer-list-gap` | `0.625rem` |
+| `$c-footer-link-font-size`, `-color`, `-text-decoration`, `-hover-text-decoration` | `inherit`, `inherit`, `none`, `underline` |
+| `$c-footer-rule-color` | `currentcolor` (the 1px rule above the legal row) |
+| `$c-footer-legal-margin-top`, `-padding-top`, `-gap` | `3rem`, `1.5rem`, `0.75rem 1.5rem` |
+| `$c-footer-legal-font-size`, `-color` | `inherit`, `inherit` |
+| `$c-footer-legal-link-color`, `-link-text-decoration` | `inherit`, `underline` (links the site puts in `legal` and `social`; without it they would show the browser blue) |

package/dist/index.js

@@ -0,0 +1,55 @@
+// src/Footer.jsx
+import { useId } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+var LEVELS = [1, 2, 3, 4, 5, 6];
+var TAG = /^[a-z][a-z0-9-]*$/i;
+var join = (...parts) => parts.filter(Boolean).join(" ");
+var filled = (value) => value !== void 0 && value !== null && value !== false && value !== "";
+var text = (value) => typeof value === "string" && value !== "";
+var clean_links = (links) => Array.isArray(links) ? links.filter((link) => link && typeof link === "object" && text(link.href) && filled(link.label)) : [];
+var clean_columns = (columns) => Array.isArray(columns) ? columns.filter((column) => column && typeof column === "object").map((column) => ({ ...column, links: clean_links(column.links) })).filter((column) => column.links.length > 0) : [];
+function Column({ title, links, Heading }) {
+  const heading_id = useId();
+  const has_title = filled(title);
+  return /* @__PURE__ */ jsxs("div", { className: "c-footer__column", children: [
+    has_title ? /* @__PURE__ */ jsx(Heading, { className: "c-footer__title", id: heading_id, children: title }) : null,
+    /* @__PURE__ */ jsx("ul", { className: "c-footer__list", "aria-labelledby": has_title ? heading_id : void 0, children: links.map((link, index) => /* @__PURE__ */ jsx("li", { className: "c-footer__item", children: /* @__PURE__ */ jsx("a", { className: "c-footer__link", href: link.href, children: link.label }) }, `${link.href}-${index}`)) })
+  ] });
+}
+function Footer({
+  brand,
+  description,
+  columns,
+  title_level = 2,
+  nav_label,
+  legal,
+  social,
+  as = "div",
+  className = "",
+  ...rest
+}) {
+  const Tag = typeof as === "string" && TAG.test(as) ? as : "div";
+  const level = Number(title_level);
+  const Heading = `h${LEVELS.includes(level) ? level : 2}`;
+  const safe_columns = clean_columns(columns);
+  const has_index = safe_columns.length > 0;
+  const has_brand = filled(brand) || filled(description);
+  const has_legal = filled(legal) || filled(social);
+  const Index = text(nav_label) ? "nav" : "div";
+  return /* @__PURE__ */ jsx(Tag, { ...rest, className: join("c-footer", className), children: /* @__PURE__ */ jsxs("div", { className: "c-footer__inner", children: [
+    has_brand || has_index ? /* @__PURE__ */ jsxs("div", { className: join("c-footer__top", has_brand && has_index && "c-footer__top--split"), children: [
+      has_brand ? /* @__PURE__ */ jsxs("div", { className: "c-footer__brand", children: [
+        filled(brand) ? /* @__PURE__ */ jsx("div", { className: "c-footer__logo", children: brand }) : null,
+        filled(description) ? /* @__PURE__ */ jsx("p", { className: "c-footer__description", children: description }) : null
+      ] }) : null,
+      has_index ? /* @__PURE__ */ jsx(Index, { className: "c-footer__nav", "aria-label": Index === "nav" ? nav_label : void 0, children: safe_columns.map((column, index) => /* @__PURE__ */ jsx(Column, { title: column.title, links: column.links, Heading }, `${column.id ?? ""}-${index}`)) }) : null
+    ] }) : null,
+    has_legal ? /* @__PURE__ */ jsxs("div", { className: "c-footer__legal-row", children: [
+      filled(legal) ? /* @__PURE__ */ jsx("div", { className: "c-footer__legal", children: legal }) : null,
+      filled(social) ? /* @__PURE__ */ jsx("div", { className: "c-footer__social", children: social }) : null
+    ] }) : null
+  ] }) });
+}
+export {
+  Footer
+};

package/package.json

@@ -1,6 +1,56 @@
 {
   "name": "@carissa-io/webkit-footer",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Carissa web kit: site footer as a labelled navigation index plus a legal row, as a React component 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/webkit-footer.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/_footer.scss

@@ -0,0 +1,118 @@
+@use 'variables' as *;
+
+.c-footer {
+    box-sizing: border-box;
+    padding-block: $c-footer-padding-block;
+    padding-inline: $c-footer-padding-inline;
+    font-family: $c-footer-font-family;
+    color: $c-footer-color;
+    background: $c-footer-background;
+
+    @media (min-width: $c-footer-padding-breakpoint) {
+        padding-inline: $c-footer-padding-inline-wide;
+    }
+}
+
+.c-footer__inner {
+    box-sizing: border-box;
+    max-width: $c-footer-max-width;
+    margin-inline: auto;
+}
+
+.c-footer__top {
+    display: grid;
+    gap: $c-footer-top-gap;
+}
+
+.c-footer__brand {
+    display: flex;
+    flex-direction: column;
+    gap: $c-footer-brand-gap;
+    min-width: 0;
+}
+
+.c-footer__logo {
+    min-width: 0;
+}
+
+.c-footer__description {
+    margin: 0;
+    max-width: $c-footer-description-max-width;
+    font-size: $c-footer-description-font-size;
+    line-height: $c-footer-description-line-height;
+    color: $c-footer-description-color;
+}
+
+.c-footer__nav {
+    display: grid;
+    grid-template-columns: repeat(auto-fit, minmax(min(100%, $c-footer-column-min-width), 1fr));
+    gap: $c-footer-column-gap;
+    min-width: 0;
+}
+
+.c-footer__column {
+    min-width: 0;
+}
+
+.c-footer__title {
+    margin: 0 0 $c-footer-title-margin-bottom;
+    font-size: $c-footer-title-font-size;
+    font-weight: $c-footer-title-font-weight;
+    letter-spacing: $c-footer-title-letter-spacing;
+    text-transform: $c-footer-title-text-transform;
+    color: $c-footer-title-color;
+}
+
+.c-footer__list {
+    display: flex;
+    flex-direction: column;
+    gap: $c-footer-list-gap;
+    margin: 0;
+    padding: 0;
+    list-style: none;
+}
+
+.c-footer__item {
+    margin: 0;
+    overflow-wrap: break-word;
+}
+
+.c-footer__link {
+    font-size: $c-footer-link-font-size;
+    color: $c-footer-link-color;
+    text-decoration: $c-footer-link-text-decoration;
+
+    &:hover {
+        text-decoration: $c-footer-link-hover-text-decoration;
+    }
+}
+
+.c-footer__legal-row {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    justify-content: space-between;
+    gap: $c-footer-legal-gap;
+    margin-top: $c-footer-legal-margin-top;
+    padding-top: $c-footer-legal-padding-top;
+    border-top: 1px solid $c-footer-rule-color;
+    font-size: $c-footer-legal-font-size;
+    color: $c-footer-legal-color;
+}
+
+.c-footer__legal,
+.c-footer__social {
+    min-width: 0;
+}
+
+.c-footer__legal a,
+.c-footer__social a {
+    color: $c-footer-legal-link-color;
+    text-decoration: $c-footer-legal-link-text-decoration;
+}
+
+@media (min-width: $c-footer-breakpoint) {
+    .c-footer__top--split {
+        grid-template-columns: $c-footer-top-columns;
+    }
+}

package/scss/_variables.scss

@@ -0,0 +1,56 @@
+// Every value is `!default`: set it before the first @use / through `with (...)` and it wins.
+//
+//   @use '@carissa-io/webkit-footer/scss' with ($c-footer-column-min-width: 12rem, $c-footer-description-max-width: 36ch);
+//
+// The defaults are neutral: colours inherit the text colour, a transparent background, a rule in currentcolor, no shadow,
+// no gradient, no motion. A theme gives the look (sizes from its type scale, `var(--c-*)` colours). The footer is the quiet
+// end of a page: small type, modest padding, the rule and the whitespace do the work.
+
+// Root and container
+$c-footer-font-family: inherit !default;
+$c-footer-color: inherit !default;
+$c-footer-background: transparent !default;
+$c-footer-max-width: 80rem !default; // the inner block, centred
+$c-footer-padding-block: 3rem !default;
+$c-footer-padding-inline: 1rem !default;
+$c-footer-padding-inline-wide: 2rem !default;
+$c-footer-padding-breakpoint: 40rem !default; // where the "wide" inline padding starts
+
+// Layout
+$c-footer-breakpoint: 40rem !default; // brand and index sit side by side from here; below it everything is stacked
+$c-footer-top-columns: minmax(0, 1fr) minmax(0, 2fr) !default; // brand, index (side by side)
+$c-footer-top-gap: 3rem !default; // brand to index
+$c-footer-column-min-width: 10rem !default; // the index is an auto-fit grid of columns at least this wide
+$c-footer-column-gap: 2rem !default; // between the columns of the index
+$c-footer-brand-gap: 1rem !default; // brand to description
+
+// Description (the measure stays short)
+$c-footer-description-font-size: inherit !default;
+$c-footer-description-line-height: 1.5 !default;
+$c-footer-description-color: inherit !default;
+$c-footer-description-max-width: 40ch !default;
+
+// Column titles
+$c-footer-title-font-size: inherit !default;
+$c-footer-title-font-weight: 700 !default;
+$c-footer-title-letter-spacing: normal !default;
+$c-footer-title-text-transform: none !default;
+$c-footer-title-color: inherit !default;
+$c-footer-title-margin-bottom: 1rem !default;
+
+// Links
+$c-footer-list-gap: 0.625rem !default;
+$c-footer-link-font-size: inherit !default;
+$c-footer-link-color: inherit !default;
+$c-footer-link-text-decoration: none !default;
+$c-footer-link-hover-text-decoration: underline !default;
+
+// Legal row
+$c-footer-rule-color: currentcolor !default; // the 1px rule above the legal row
+$c-footer-legal-margin-top: 3rem !default;
+$c-footer-legal-padding-top: 1.5rem !default;
+$c-footer-legal-gap: 0.75rem 1.5rem !default; // row gap, column gap (the row wraps)
+$c-footer-legal-font-size: inherit !default;
+$c-footer-legal-color: inherit !default;
+$c-footer-legal-link-color: inherit !default; // links the site puts in the legal and social slots (they follow the row, not the browser's blue)
+$c-footer-legal-link-text-decoration: underline !default;

package/scss/index.scss

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