burgee/brand

import { opposedField, burgeeFlagPath, fieldId, … } from 'burgee/brand';

function burgeeBody(brand: BurgeeBrand, id?: string, moving?: boolean): string;

function burgeeFlagPath(): string;

function chargeGroup(colors: BurgeeColors, scale?: number): string;

function chargeRotation(): string;

function chargeTransform(scale?: number): string;

const brand = defineBurgee({
  name: 'burgee',
  mark: { lead: '#a84c17', follow: '#0a6b47' },
  field: [
    { offset: 0, color: '#0a6b47' },
    { offset: 0.5, color: '#0a0a0a' },
    { offset: 1, color: '#a84c17' },
  ],
});
writeFileSync('icon.svg', brand.favicon());

function defineBurgee(brand: BurgeeBrand): Burgee;

function fieldId(brand: BurgeeBrand): string;

function opposedField(colors: BurgeeColors, ground?: string): FieldStop[];

function placeCharge(markup: string, scale?: number): string;

const BURGEE_ANGLE: number;

const BURGEE_FLAG: readonly Point[];

const CHARGE: {
    readonly scale: 0.4;
    readonly x: 42;
    readonly y: 50;
};

const DEFAULT_GROUND = "#0a0a0a";

const FIELD_AXIS: {
    readonly x1: 25;
    readonly y1: 6.7;
    readonly x2: 75;
    readonly y2: 93.3;
};

interface Bordure {
    color: string;
    /** Visible thickness, in mark-space units. */
    width: number;
}

interface Burgee {
    /** The flag alone, square, at any size. */
    flag(size?: number): string;
    /**
     * The same mark with its sheen sweeping across it, for a page that can afford
     * motion — a site header, a docs hero. Identical to {@link Burgee.flag} when
     * no `sheen` is declared, and parked still under `prefers-reduced-motion`.
     *
     * Not the favicon and not the README: a tab icon that shimmers is a tab icon
     * that distracts.
     */
    alive(size?: number): string;
    /** Favicon master. One file serves both themes — the flag carries its own field. */
    favicon(size?: number): string;
    /** Social card, 1200×630. */
    og(options?: CardOptions): string;
    /** Article cover, 1000×420. */
    cover(options?: CardOptions): string;
    /** Flag and wordmark, laid out horizontally. */
    lockup(options?: CardOptions): string;
    /** The gradient id this brand emits, for callers that need to match it. */
    fieldId(): string;
}

interface BurgeeBrand {
    /** Accessible name for the flag. Without one the flag is decorative. */
    name?: string;
    /**
     * The charge, as a two-colour bar pair. Ignored when {@link BurgeeBrand.charge}
     * is given — that is the escape hatch for a CLI bringing its own glyph.
     */
    mark: BurgeeColors;
    /**
     * Your own charge instead of the bars: SVG markup drawn in a 0 0 100 100 box,
     * which burgee places and scales for you. Everything else — the swallowtail,
     * the reversed field, the sizes — still comes from this one declaration.
     *
     * The markup is emitted verbatim, so it is yours to trust: this runs at build
     * time on a file you wrote, not on anything a user supplies at runtime.
     */
    charge?: string;
    /**
     * Your own silhouette instead of the swallowtail: SVG path data in the same
     * `0 0 100 100` box, filled with the field and carrying the charge exactly as
     * the flag does. For a sibling brand whose name is not a flag — a roundel is
     * rings, a parrot is a parrot — the shape is the whole point, and drawing it
     * here keeps every other projection (favicon, lockup, OG, cover) intact.
     *
     * Filled `evenodd`, so a subpath drawn inside another cuts a hole through it:
     * that is how a ring gets its centre and an eye gets its white. Subpaths that
     * are meant to read as one solid body must not overlap.
     *
     * Emitted verbatim, like {@link BurgeeBrand.charge}: a build-time value you
     * wrote, never anything a user supplies at runtime.
     */
    shape?: string;
    /**
     * A sheen: a soft highlight laid across the field, `0` to `1`, where the
     * number is how bright its brightest point is. Depth, not decoration — a flat
     * gradient reads as printed ink, and one light source makes the same shape
     * read as an object with a front.
     *
     * It is drawn INSIDE the silhouette (clipped to it), so it never softens the
     * outline the mark is recognised by, and it sits under the charge, so it never
     * touches the contrast the charge was measured at.
     *
     * The same layer is what moves in {@link Burgee.alive}.
     */
    sheen?: number;
    /**
     * A bevel: how strongly the mark's own edge catches the light, `0` to `1`.
     *
     * The whole of the third dimension a logo can afford. Two copies of the
     * silhouette stroked and clipped to itself — light offset up toward the light
     * source, dark offset away — so the edge lifts and the face stays flat. No
     * extrusion, no renderer, and nothing that stops it being a 16px favicon: the
     * bevel is sub-pixel there and simply disappears, which is the correct
     * behaviour rather than a compromise.
     */
    bevel?: number;
    /**
     * Markings: SVG markup in the same `0 0 100 100` box as {@link BurgeeBrand.shape},
     * drawn over the field and under the charge.
     *
     * One path can hold one fill, and some marks are not one colour — a roundel is
     * concentric rings, a caique has a black cap over an orange throat over a white
     * belly. Those are markings ON the body, not the body, and they are declared
     * here rather than by stacking whole brands on top of each other.
     *
     * Emitted verbatim, like {@link BurgeeBrand.charge}: a build-time value you
     * wrote, never anything a user supplies at runtime.
     */
    markings?: string;
    /**
     * The field, as gradient stops along {@link FIELD_AXIS}. One stop is a flat
     * field. Keep a dark stop under the charge or the mark will not read.
     */
    field: readonly FieldStop[];
    /**
     * The outline, outermost band first.
     *
     * One band is enough when you control the ground. Two is what you want when
     * you do not: no single flat colour clears 3:1 against both a near-black and a
     * white page, so a dark outer band and a light inner band are given, and
     * whichever one the ground does not match is the one carrying the silhouette.
     * That is one asset that holds its outline anywhere — which a favicon, having
     * no stylesheet to read a theme from, actually needs.
     *
     * `width` is the visible thickness of each band in mark-space units.
     */
    bordure?: Bordure | readonly Bordure[];
}

interface BurgeeColors {
    /** Leading bar, hoist side. */
    lead: string;
    /** Following bar, fly side. */
    follow: string;
}

interface CardOptions {
    width?: number;
    height?: number;
    /** Large line. Defaults to the brand name. */
    title?: string;
    /** Small line under it; wraps. */
    subtitle?: string;
    theme?: 'light' | 'dark';
    background?: string;
    foreground?: string;
    muted?: string;
}

interface FieldStop {
    offset: number;
    color: string;
}

type Point = readonly [number, number];