duckfn-docs-kit 0.1.0

package/src/dom.ts

@@ -0,0 +1,109 @@
+/**
+ * DOM helpers shared by the custom elements.
+ *
+ * `HTMLElementBase` is the whole reason this module exists: the element classes
+ * `extend` it, but Docusaurus imports this package into Node during static
+ * prerendering, where the global `HTMLElement` does not exist and evaluating
+ * `class X extends HTMLElement` would throw. Falling back to an empty base
+ * class keeps module evaluation safe on the server; the real `HTMLElement` is
+ * picked up in the browser, where the elements are actually defined and run.
+ */
+
+export const HTMLElementBase: typeof HTMLElement =
+  typeof HTMLElement !== 'undefined'
+    ? HTMLElement
+    : (class {} as unknown as typeof HTMLElement);
+
+/**
+ * The tag's props that hold a value `el()` can assign as-is — `href`, `src`,
+ * `alt`, `width`, `hidden`, and so on.
+ *
+ * Methods and object-valued props are filtered out, so an options bag can never
+ * carry `appendChild`, `style`, `dataset` or `classList`. Getter-only props
+ * (`origin`, `clientWidth`) do pass the filter; assigning one throws in strict
+ * mode, which is loud enough to be caught the first time it runs.
+ */
+type ValueProps<T> = {
+  [P in keyof T as T[P] extends Function
+    ? never
+    : T[P] extends object
+      ? never
+      : P]?: T[P];
+};
+
+/**
+ * Options for `el()`: the tag's own props, narrowed to that tag, plus two
+ * shorthands and the attribute escape hatch.
+ */
+export type ElOptions<T extends Element> = ValueProps<T> & {
+  /** Shorthand for `className`. */
+  class?: string;
+  /** Shorthand for `textContent`. */
+  text?: string;
+  /**
+   * Attributes that have no matching prop: `aria-*`, `data-*`, and
+   * custom-element attributes. Everything else goes through a property, so a
+   * boolean or a number keeps its real type instead of being stringified.
+   */
+  attrs?: Record<string, string>;
+};
+
+/**
+ * `document.createElement` with per-tag typed options and an optional `init`
+ * callback.
+ *
+ * The one sanctioned way to build nodes in this package: it returns a live
+ * element (held in a class field by the caller), never an HTML string.
+ *
+ * The options are narrowed to the tag, so a typo, a wrong value type, a method
+ * name or an object-valued prop is a compile error:
+ *
+ * ```ts
+ * el('img', {class: 'dfk-logo', alt: '', width: 480});
+ * ```
+ *
+ * `init` describes a subtree in place, for structure that is never referenced
+ * again and therefore needs no field:
+ *
+ * ```ts
+ * this.root.append(
+ *   el('span', {class: 'dfk-next-card-body'}, (body) => body.append(this.#title, this.#details)),
+ *   this.#arrow,
+ * );
+ * ```
+ *
+ * Nodes touched later stay in fields. A field initializer must not read a
+ * `#field` declared below it (initializers run in declaration order, so that is
+ * a TDZ error) — pass `init` from the constructor, where every field is ready.
+ */
+export function el<K extends keyof HTMLElementTagNameMap>(
+  tag: K,
+  // A function is the `init` callback, so options can be skipped:
+  // `el('span', (span) => (span.textContent = label))`.
+  options?:
+    | ElOptions<HTMLElementTagNameMap[K]>
+    | ((node: HTMLElementTagNameMap[K]) => void),
+  init?: (node: HTMLElementTagNameMap[K]) => void,
+): HTMLElementTagNameMap[K] {
+  const node = document.createElement(tag);
+  const build = typeof options === 'function' ? options : init;
+  if (typeof options !== 'function' && options) {
+    const {class: className, text, attrs, ...props} = options;
+    if (className !== undefined) {
+      node.className = className;
+    }
+    if (text !== undefined) {
+      node.textContent = text;
+    }
+    for (const [name, value] of Object.entries(props)) {
+      if (value !== undefined) {
+        (node as unknown as Record<string, unknown>)[name] = value;
+      }
+    }
+    for (const [name, value] of Object.entries(attrs ?? {})) {
+      node.setAttribute(name, value);
+    }
+  }
+  build?.(node);
+  return node;
+}

package/src/home/DfkFeatures.ts

@@ -0,0 +1,78 @@
+import type {IconifyIconHTMLElement} from 'iconify-icon';
+import {el, HTMLElementBase} from '../dom';
+import {homeStyles} from './styles';
+import type {FeatureItem} from '../types';
+
+/**
+ * `<dfk-features>` — the "Why duckfn" grid of feature cards. Ported from the
+ * home page's `Features()`.
+ *
+ * Retained-mode: the grid is built once and each card (a {@link DfkFeatureCard})
+ * holds its own nodes. `setFeatures()` grows or shrinks the list to the new
+ * length and mutates the cards in place — the grid is never cleared and rebuilt.
+ *
+ * The tree lives in a shadow root (adopting the shared `homeStyles()` sheet);
+ * see `DfkHero` for why the theme crosses the boundary through custom
+ * properties.
+ */
+export class DfkFeatures extends HTMLElementBase {
+  readonly #section = el('section', {class: 'dfk-section'});
+  readonly #inner = el('div', {class: 'dfk-section-inner'});
+  readonly #heading = el('h2', {class: 'dfk-section-title'});
+  readonly #grid = el('div', {class: 'dfk-feature-grid'});
+  readonly #cards: DfkFeatureCard[] = [];
+
+  constructor() {
+    super();
+    this.#inner.append(this.#heading, this.#grid);
+    this.#section.appendChild(this.#inner);
+    const shadow = this.attachShadow({mode: 'open'});
+    shadow.adoptedStyleSheets = [homeStyles()];
+    shadow.appendChild(this.#section);
+  }
+
+  setSectionTitle(text: string): void {
+    this.#heading.textContent = text;
+  }
+
+  setFeatures(items: readonly FeatureItem[]): void {
+    while (this.#cards.length > items.length) {
+      this.#cards.pop()?.root.remove();
+    }
+    while (this.#cards.length < items.length) {
+      const card = new DfkFeatureCard();
+      this.#cards.push(card);
+      this.#grid.appendChild(card.root);
+    }
+    items.forEach((item, index) => this.#cards[index].setFeature(item));
+  }
+}
+
+/** One feature card: an icon chip, a title and a description. Built once. */
+class DfkFeatureCard {
+  readonly root = el('article', {class: 'dfk-feature-card'});
+  readonly #icon: IconifyIconHTMLElement = el('iconify-icon', {
+    class: 'dfk-feature-icon',
+    attrs: {'aria-hidden': 'true'},
+  });
+  readonly #title = el('h3', {class: 'dfk-feature-title'});
+  readonly #details = el('p', {class: 'dfk-feature-details'});
+
+  constructor() {
+    // The chip only wraps the icon and is never touched again, so it is
+    // described in place instead of being held in a field.
+    this.root.append(
+      el('span', {class: 'dfk-feature-icon-chip'}, (chip) =>
+        chip.appendChild(this.#icon),
+      ),
+      this.#title,
+      this.#details,
+    );
+  }
+
+  setFeature(item: FeatureItem): void {
+    this.#icon.setAttribute('icon', item.icon);
+    this.#title.textContent = item.title;
+    this.#details.textContent = item.details;
+  }
+}

package/src/home/DfkHero.ts

@@ -0,0 +1,128 @@
+import type {IconifyIconHTMLElement} from 'iconify-icon';
+import {el, HTMLElementBase} from '../dom';
+import {homeStyles} from './styles';
+import type {HeroAction, HeroBadge, HeroLink} from '../types';
+
+/**
+ * `<dfk-hero>` — the landing hero: logo, title, tagline, the two call-to-action
+ * buttons and the badge row. Ported from the Docusaurus home page's `Hero()`.
+ *
+ * Retained-mode: every node is held in a field, the structure is assembled once
+ * in the constructor and the `set*` methods only mutate the nodes they own.
+ *
+ * The tree lives in a shadow root (adopting the shared `homeStyles()` sheet), so
+ * the site's global CSS cannot reach it; theme colours cross the boundary
+ * through the inherited `--duckfn-*` / `--ifm-*` custom properties.
+ */
+export class DfkHero extends HTMLElementBase {
+  readonly #section = el('section', {class: 'dfk-hero'});
+  readonly #inner = el('div', {class: 'dfk-hero-inner'});
+  readonly #stage = el('span', {class: 'dfk-logo-stage'});
+  // The <h1> spells out the name, so the logo is decorative: alt="".
+  readonly #logo = el('img', {
+    class: 'dfk-logo',
+    alt: '',
+    width: 480,
+    height: 480,
+  });
+  readonly #title = el('h1', {class: 'dfk-title'});
+  readonly #tagline = el('p', {class: 'dfk-tagline'});
+  readonly #actions = el('div', {class: 'dfk-actions'});
+  readonly #primary = el('a', {class: 'dfk-button-primary'});
+  readonly #primaryLabel = el('span');
+  readonly #secondary = el('a', {class: 'dfk-button-secondary'});
+  readonly #secondaryIcon: IconifyIconHTMLElement = el('iconify-icon', {
+    class: 'dfk-button-icon',
+    attrs: {'aria-hidden': 'true'},
+  });
+  readonly #secondaryLabel = el('span');
+  readonly #badges = el('div', {class: 'dfk-badges'});
+  readonly #badgeLinks: HTMLAnchorElement[] = [];
+
+  constructor() {
+    super();
+    this.#stage.appendChild(this.#logo);
+    this.#primary.appendChild(this.#primaryLabel);
+    this.#secondary.append(this.#secondaryIcon, this.#secondaryLabel);
+    this.#actions.append(this.#primary, this.#secondary);
+    this.#inner.append(
+      this.#stage,
+      this.#title,
+      this.#tagline,
+      this.#actions,
+      this.#badges,
+    );
+    this.#section.appendChild(this.#inner);
+    // A custom element's constructor may call `attachShadow` (it only must not
+    // add children or attributes to `this`), so the whole tree lives in the
+    // shadow root from the first moment the element exists — the setters are
+    // safe to call before the element is even connected.
+    const shadow = this.attachShadow({mode: 'open'});
+    shadow.adoptedStyleSheets = [homeStyles()];
+    shadow.appendChild(this.#section);
+  }
+
+  setLogo(src: string): void {
+    this.#logo.src = src;
+  }
+
+  setTitle(text: string): void {
+    this.#title.textContent = text;
+  }
+
+  setTagline(text: string): void {
+    this.#tagline.textContent = text;
+  }
+
+  /** The "Get started" button: an internal link, so it stays in the same tab. */
+  setPrimaryAction(link: HeroLink): void {
+    this.#fillLink(this.#primary, this.#primaryLabel, link, false);
+  }
+
+  /** The GitHub button: always external, always carries the glyph. */
+  setSecondaryAction(action: HeroAction): void {
+    this.#fillLink(this.#secondary, this.#secondaryLabel, action, true);
+    this.#secondaryIcon.setAttribute('icon', action.icon);
+  }
+
+  setBadges(badges: readonly HeroBadge[]): void {
+    // Grow/shrink the row to the new length and reuse the links already there.
+    while (this.#badgeLinks.length > badges.length) {
+      this.#badgeLinks.pop()?.remove();
+    }
+    while (this.#badgeLinks.length < badges.length) {
+      const link = el('a', {
+        class: 'dfk-badge',
+        target: '_blank',
+        rel: 'noopener noreferrer',
+      });
+      link.appendChild(el('img', {class: 'dfk-badge-image'}));
+      this.#badgeLinks.push(link);
+      this.#badges.appendChild(link);
+    }
+    badges.forEach((badge, index) => {
+      const link = this.#badgeLinks[index];
+      link.href = badge.href;
+      const image = link.firstElementChild as HTMLImageElement;
+      image.src = badge.src;
+      image.alt = badge.alt;
+    });
+  }
+
+  #fillLink(
+    anchor: HTMLAnchorElement,
+    label: HTMLElement,
+    link: HeroLink,
+    external: boolean,
+  ): void {
+    anchor.href = link.href;
+    label.textContent = link.label;
+    if (external) {
+      anchor.target = '_blank';
+      anchor.rel = 'noopener noreferrer';
+    } else {
+      anchor.removeAttribute('target');
+      anchor.removeAttribute('rel');
+    }
+  }
+}

package/src/home/DfkNextSteps.ts

@@ -0,0 +1,73 @@
+import type {IconifyIconHTMLElement} from 'iconify-icon';
+import {el, HTMLElementBase} from '../dom';
+import {homeStyles} from './styles';
+import type {NextStepItem} from '../types';
+
+/**
+ * `<dfk-next-steps>` — the "Where to go next" row of link cards. Ported from
+ * the home page's `NextSteps()`.
+ *
+ * Same retained-mode shape as `DfkFeatures`: the grid is built once, each card
+ * holds its own nodes, `setSteps()` grows/shrinks the list and mutates in place.
+ * The tree lives in a shadow root like the other `dfk-*` elements.
+ */
+export class DfkNextSteps extends HTMLElementBase {
+  readonly #section = el('section', {class: 'dfk-section'});
+  readonly #inner = el('div', {class: 'dfk-section-inner'});
+  readonly #heading = el('h2', {class: 'dfk-section-title'});
+  readonly #grid = el('div', {class: 'dfk-next-grid'});
+  readonly #cards: DfkNextStepCard[] = [];
+
+  constructor() {
+    super();
+    this.#inner.append(this.#heading, this.#grid);
+    this.#section.appendChild(this.#inner);
+    const shadow = this.attachShadow({mode: 'open'});
+    shadow.adoptedStyleSheets = [homeStyles()];
+    shadow.appendChild(this.#section);
+  }
+
+  setSectionTitle(text: string): void {
+    this.#heading.textContent = text;
+  }
+
+  setSteps(items: readonly NextStepItem[]): void {
+    while (this.#cards.length > items.length) {
+      this.#cards.pop()?.root.remove();
+    }
+    while (this.#cards.length < items.length) {
+      const card = new DfkNextStepCard();
+      this.#cards.push(card);
+      this.#grid.appendChild(card.root);
+    }
+    items.forEach((item, index) => this.#cards[index].setStep(item));
+  }
+}
+
+/** One "next step" card: the whole card is the link. Built once. */
+class DfkNextStepCard {
+  readonly root = el('a', {class: 'dfk-next-card'});
+  readonly #title = el('span', {class: 'dfk-next-card-title'});
+  readonly #details = el('span', {class: 'dfk-next-card-details'});
+  readonly #arrow: IconifyIconHTMLElement = el('iconify-icon', {
+    class: 'dfk-next-card-arrow',
+    attrs: {icon: 'lucide:arrow-right', 'aria-hidden': 'true'},
+  });
+
+  constructor() {
+    // The body only groups the two text spans and is never touched again, so it
+    // is described in place instead of being held in a field.
+    this.root.append(
+      el('span', {class: 'dfk-next-card-body'}, (body) =>
+        body.append(this.#title, this.#details),
+      ),
+      this.#arrow,
+    );
+  }
+
+  setStep(item: NextStepItem): void {
+    this.root.href = item.href;
+    this.#title.textContent = item.title;
+    this.#details.textContent = item.details;
+  }
+}