Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 32 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,9 +42,39 @@ import { Header, Footer, HeaderButton, PersonIcon, themeBoot } from '@addiscorp/
- **The menu**: the brand button opens it; ⌘M / Ctrl+M opens and closes it; ⌘S, Ctrl+S or `/` opens it on search; typing anywhere searches; ↑ ↓ move, Enter opens, 1–9 open a numbered tile, Esc closes, `?` lists the shortcuts. A click outside or a navigation closes it.
- **Groups** are tiles (numbered 1–9 in order across groups) or rows (`layout: 'list'`); a `searchOnly` group appears only as search matches. An item has a `href` or an `onSelect`, an optional `icon`, `detail` and `keywords`.
- **`HeaderButton`**: a round button with a popover, one popover open at a time with the menu: account, notifications (`badge`), settings, or anything else.
- **`Footer`**: who makes the site (Addis Corp by default; `owner` changes it), the site's name, the light/dark switch.
- **`Footer`**: who makes the site (Addis Corp by default; `owner` changes it), the product's license when `license` is passed, the site's name, the light/dark switch.
- **Theme**: `themeBoot` sets light or dark before paint (a `theme` cookie wins, else the system); `ThemeToggle` switches and remembers.

## The license

Addis products are MIT (APS 17). One `License` describes a product's license,
and the same value drives everything a site shows about it, so the footer, the
badge, the page and the LICENSE file can't disagree.

```tsx
import { LicenseView, MIT_LICENSE, mitLicense, type License } from '@addiscorp/kit';

const license: License = {}; // MIT, Copyright (c) 2026 Sami Fouad
const harar: License = { source: 'https://github.com/addiscorp/harar' }; // public: the source is linked
const p8: License = { // a fork keeps its upstream notices, above ours
github: 'samifouad',
upstream: [{ year: 2025, holder: 'Di Wu', github: 'wudi' }],
preface: 'p8 began as a fork of php-rs by Di Wu.',
};

<ToolSite tool="harar" license={harar}>…</ToolSite> // footer: "MIT · © 2026 Sami Fouad" → /license/, then "source"
<Hero … status="alpha" license={harar} /> // ( Status: Alpha ) ( License: MIT ) above the buttons; License → /license/
<ProductPills status="beta" license={license} /> // the same pair on any other page
<DocsLayout … license={harar}>…</DocsLayout> // the same footer line
<Footer site="…" license={license} /> // any site's footer
<LicenseView product="harar" license={harar} note={…} /> // the page: summary line, note, source, the full text
```

- **`mitLicense(license)`** is the LICENSE file's text, byte for byte (tested against harar's and p8's files); **`MIT_LICENSE`** is the default one.
- **`source`** is only for a public repository. Without it nothing links to a repository and nothing says "open source".
- **`note`** on the page is for what the product must add: a part that keeps an upstream license.
- **`href`** moves the page from `/license/`.

## Make it yours

- **Colours and fonts** are variables. Set your brand's after importing `kit.css`:
Expand Down Expand Up @@ -86,6 +116,7 @@ import { ToolSite, Hero, Why, DocsLayout, Code, Step, Callout } from '@addiscorp
</DocsLayout>
```

- **Status and license**: nothing is 1.0 yet, so every tool's hero says where it stands and how it's licensed, in two pills of one shape, side by side above the buttons: ( Status: Alpha | Beta ) ( License: MIT ). The pills carry only that; anything longer goes in the words. `ProductPills` is the pair for any other page; `StatusPill`, `LicensePill`, `statusText` and `LICENSE_PILL_TEXT` are its parts.
- **The header** is the mark, the name and `docs`. A tool that has more to link adds it after docs with `links` (p8: `links={[{ label: 'test suite', href: 'https://p8-test-suite.addis.gg' }]}`).
- **The reel** is CSS only: its scenes play in turn, 5 s each, and each scene's lines appear one after another. With reduced motion it shows the first scene, still.
- **Colours**: `data-tool` picks the tool's palette (`src/tool/palettes.css`, generated from its colour layout): one pale ground in light mode, a ground tinted with the brand in dark. The kit's footer and theme switch take the same colours.
Expand Down
4 changes: 2 additions & 2 deletions package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "@addiscorp/kit",
"version": "0.2.7",
"version": "0.3.0",
"description": "The header, footer, theme and tool-site layout every Addis site shares, in each project's own brand colours.",
"license": "MIT",
"type": "module",
Expand Down
8 changes: 7 additions & 1 deletion src/footer/index.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@
// light/dark switch.
import type { ReactNode } from 'react';
import { ThemeToggle } from '../theme/index.js';
import type { LinkComponent } from '../header/index.js';
import { LicenseLink, type License } from '../license/index.js';

export type Owner = { name: string; href: string; logo: ReactNode };

Expand All @@ -22,16 +24,20 @@ export type FooterProps = {
children?: ReactNode;
/** A small line under the footer row, e.g. trademark notices. */
note?: ReactNode;
/** The product's license: `MIT · © 2026 Sami Fouad`, linking to the license page. */
license?: License;
Link?: LinkComponent;
};

export function Footer({ site, owner = ADDIS, year = new Date().getFullYear(), children, note }: FooterProps) {
export function Footer({ site, owner = ADDIS, year = new Date().getFullYear(), children, note, license, Link }: FooterProps) {
return (
<footer className="ak-foot">
<a className="ak-credit" href={owner.href}>
{owner.logo}
© {year} {owner.name}
</a>
<span className="ak-foot-end">
{license && <LicenseLink license={license} Link={Link} />}
{children}
<span>{site}</span>
<ThemeToggle />
Expand Down
2 changes: 2 additions & 0 deletions src/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -4,4 +4,6 @@
export * from './header/index.js';
export * from './footer/index.js';
export * from './theme/index.js';
export * from './license/index.js';
export * from './status/index.js';
export * from './tool/index.js';
33 changes: 33 additions & 0 deletions src/kit.css
Original file line number Diff line number Diff line change
Expand Up @@ -109,6 +109,39 @@
.ak-credit img, .ak-owner-mark { width: 32px; height: 32px; border-radius: 50%; }
.ak-foot-end { display: inline-flex; align-items: center; gap: 12px; }
.ak-foot-note { flex-basis: 100%; margin: 0; font-size: 11px; line-height: 1.6; color: var(--ak-soft); opacity: .8; }
.ak-foot-end { flex-wrap: wrap; justify-content: flex-end; }

/* Status: where a product stands. Beta is a filled dot, alpha a hollow one. */
.ak-pills { display: flex; flex-wrap: wrap; align-items: center; gap: 8px; }
.ak-pill { display: inline-flex; align-items: center; gap: 8px; height: 28px; padding: 0 12px 0 10px; border: 1px solid var(--ak-edge); border-radius: 999px; background: var(--ak-panel); color: var(--ak-soft); font: 12px/1 var(--ak-font); text-decoration: none; white-space: nowrap; }
.ak-pill b { color: var(--ak-ink); font-weight: 600; }
.ak-pill i { flex: none; width: 7px; height: 7px; border-radius: 50%; background: var(--ak-accent); box-shadow: 0 0 0 1.5px var(--ak-accent) inset; }
.ak-status[data-status="alpha"] i { background: transparent; }
/* Stronger than a site's own `a { color }`, so the link pill reads exactly like the status pill. */
.ak-pills > .ak-pill { color: var(--ak-soft); }
.ak-pills > a.ak-pill:hover { border-color: var(--ak-accent); color: var(--ak-ink); }

/* The license (APS 17): the footer line, the hero badge and the license page. */
.ak-license a { color: inherit; text-decoration: none; }
.ak-license a:hover { color: var(--ak-ink); text-decoration: underline; text-underline-offset: 3px; }
.ak-license-page { max-width: 760px; padding: 48px 0 72px; color: var(--ak-ink); }
.ak-license-eyebrow { font: 600 12px var(--ak-font); letter-spacing: .11em; text-transform: uppercase; color: var(--ak-soft); }
.ak-license-page h1 { font: 800 clamp(32px, 5vw, 46px)/1.1 var(--ak-display); letter-spacing: -0.03em; margin: 6px 0 16px; }
.ak-license-summary { font-size: 18px; line-height: 1.5; margin: 0 0 10px; max-width: 58ch; }
.ak-license-note, .ak-license-source { color: var(--ak-soft); margin: 8px 0; max-width: 64ch; line-height: 1.55; }
.ak-license-page .ak-license-note a, .ak-license-page .ak-license-source a { color: var(--ak-accent); text-underline-offset: 3px; }
.ak-license-text { margin: 28px 0 0; padding: 24px 28px; background: var(--ak-panel); border: 1px solid var(--ak-edge); border-radius: 12px; font: 13px/1.7 var(--ak-font); white-space: pre-wrap; overflow-wrap: anywhere; }
@media (min-width: 601px) {
/* The license block, then a rule, then the site's name. */
.ak-foot-end .ak-license { padding-right: 12px; border-right: 1px solid var(--ak-edge); }
}
@media (max-width: 600px) {
.ak-license-page { padding: 32px 0 48px; }
/* The file's lines are wrapped for 80 columns: on a phone each paragraph reflows instead. */
.ak-license-text { padding: 16px; font-size: 12px; line-height: 1.65; white-space: normal; }
.ak-license-text span { display: block; }
.ak-license-text span + span { margin-top: 1em; }
}

/* The theme switch */
.ak-theme-toggle { box-sizing: border-box; border: 0; background: transparent; border-radius: 4px; color: inherit; cursor: pointer; display: inline-flex; height: 32px; width: 32px; align-items: center; justify-content: center; padding: 8px; }
Expand Down
123 changes: 123 additions & 0 deletions src/license/index.tsx
Original file line number Diff line number Diff line change
@@ -0,0 +1,123 @@
// The license, once (APS 17: Addis products are MIT, `Copyright (c) <year> Sami Fouad`).
// One description of a product's license drives all four places a site shows
// it, so they can't disagree: the text (`mitLicense`), the footer line
// (`LicenseLink`), the hero pill (`LicensePill`, in ../status) and the page (`LicenseView`).
import { Fragment, type ReactNode } from 'react';
import type { LinkComponent } from '../header/index.js';

/** A copyright line: `Copyright (c) 2025 Di Wu (GitHub: wudi)`. */
export type Notice = { year: number; holder: string; github?: string };

export type License = {
/** The year in our copyright line. */
year?: number;
/** Who holds it; APS 17 makes it `Sami Fouad`. */
holder?: string;
/** A GitHub handle after our name, when the file has one: `(GitHub: samifouad)`. */
github?: string;
/** The notices a fork arrived with, kept above ours, in their order (APS 17: never dropped). */
upstream?: Notice[];
/** A line between the title and the notices, e.g. where a fork began. */
preface?: string;
/**
* The public source. Only a public repository passes it: without it the
* kit links to no repository and never says "open source".
*/
source?: string;
/** Where the site serves the license page. */
href?: string;
};

export const LICENSE_YEAR = 2026;
export const LICENSE_HOLDER = 'Sami Fouad';
export const LICENSE_HREF = '/license/';

/** The MIT permission notice and disclaimer, as every Addis LICENSE file has it. */
export const MIT_PERMISSION = `Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
`;

const ours = (license: License): Notice => ({
year: license.year ?? LICENSE_YEAR,
holder: license.holder ?? LICENSE_HOLDER,
github: license.github,
});

const noticeLine = (n: Notice) => `Copyright (c) ${n.year} ${n.holder}${n.github ? ` (GitHub: ${n.github})` : ''}`;

/** The LICENSE file's text, byte for byte: title, preface, every notice (upstream first, ours last), the permission. */
export function mitLicense(license: License = {}): string {
const notices = [...(license.upstream ?? []), ours(license)].map(noticeLine).join('\n');
return ['MIT License', ...(license.preface ? [license.preface] : []), notices, MIT_PERMISSION].join('\n\n');
}

/** The default: `MIT License`, `Copyright (c) 2026 Sami Fouad`, the permission. */
export const MIT_LICENSE = mitLicense();

/** The short line a footer shows: `MIT · © 2026 Sami Fouad`. */
export function licenseLine(license: License = {}): string {
const { year, holder } = ours(license);
return `MIT · © ${year} ${holder}`;
}

const PlainLink: LinkComponent = (props) => <a {...props} />;

/** For the footer: the line, linking to the license page, and the source when it's public. */
export function LicenseLink({ license = {}, Link = PlainLink }: { license?: License; Link?: LinkComponent }) {
return (
<span className="ak-license">
<Link href={license.href ?? LICENSE_HREF}>{licenseLine(license)}</Link>
{license.source && <> · <a href={license.source}>source</a></>}
</span>
);
}


/** What MIT lets you do, in a line: `harar is MIT licensed: use it, change it, ship it, …`. */
export const licenseSummary = (product: string) =>
`${product} is MIT licensed: use it, change it, ship it, commercially or not; keep the notice.`;

/**
* The license page: a heading, the plain-language line, anything the product
* must add (a part under another license), the source when it's public, and
* the full text. Styled by the kit's `--ak-*` tokens, so it takes any site's colours.
*/
export function LicenseView({ product, license = {}, note, title = 'MIT License' }: {
/** The product's name as the site shows it: `harar`, `the p8 test suite`. */
product: string;
license?: License;
/** A line under the summary, e.g. a part that keeps an upstream license. */
note?: ReactNode;
title?: string;
}) {
return (
<section className="ak-license-page" aria-labelledby="ak-license-title">
<div className="ak-license-eyebrow">License</div>
<h1 id="ak-license-title">{title}</h1>
<p className="ak-license-summary">{licenseSummary(product)}</p>
{note && <p className="ak-license-note">{note}</p>}
{license.source && <p className="ak-license-source">The source: <a href={license.source}>{license.source.replace(/^https?:\/\//, '')}</a></p>}
{/* A span per paragraph: the text is the file's, byte for byte, and a phone can reflow its hard-wrapped lines. */}
<pre className="ak-license-text">
{mitLicense(license).split('\n\n').map((paragraph, i) => (
<Fragment key={i}>{i > 0 && '\n\n'}<span>{paragraph}</span></Fragment>
))}
</pre>
</section>
);
}
49 changes: 49 additions & 0 deletions src/status/index.tsx
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
// Two pills, side by side, the same on every site: where a product stands, so
// nobody mistakes it for a 1.0, and its license: ( Status: Beta ) ( License: MIT ).
// They carry only that; anything longer belongs in the page's words.
import type { LinkComponent } from '../header/index.js';
import { LICENSE_HREF, type License } from '../license/index.js';

/** How far along a product is. Nothing here is 1.0 yet. */
export type Stage = 'alpha' | 'beta';

const STAGE_NAMES: Record<Stage, string> = { alpha: 'Alpha', beta: 'Beta' };

/** The status pill's words: `Status: Beta`. */
export const statusText = (status: Stage) => `Status: ${STAGE_NAMES[status]}`;

/** The license pill's words. */
export const LICENSE_PILL_TEXT = 'License: MIT';

const PlainLink: LinkComponent = (props) => <a {...props} />;

/** The status pill. Beta has a filled dot, alpha a hollow one. */
export function StatusPill({ status }: { status: Stage }) {
return (
<span className="ak-pill ak-status" data-status={status}>
<i aria-hidden="true" />
<span>Status: <b>{STAGE_NAMES[status]}</b></span>
</span>
);
}

/** The license pill, linking to the license page. */
export function LicensePill({ license = {}, Link = PlainLink }: { license?: License; Link?: LinkComponent }) {
return (
<Link className="ak-pill ak-license-pill" href={license.href ?? LICENSE_HREF}>
<i aria-hidden="true" />
<span>License: <b>MIT</b></span>
</Link>
);
}

/** ( Status: Beta ) ( License: MIT ): the pair, side by side, either one alone when only it is given. */
export function ProductPills({ status, license, Link }: { status?: Stage; license?: License; Link?: LinkComponent }) {
if (!status && !license) return null;
return (
<div className="ak-pills">
{status && <StatusPill status={status} />}
{license && <LicensePill license={license} Link={Link} />}
</div>
);
}
Loading
Loading