v0.2.0

What's Changed

Documentation

• README expanded with a full API reference for the three JSON
  endpoints (/styleguide/api/components, /api/pages, /api/fields)
  — response shape, ordering, caching behavior, and the pattern for
  adding a fourth endpoint. Also adds a Constructor config table
  covering every key accepted by Styleguide::__construct() (including
  the previously undocumented twig_options, typography_config, and
  namespaces), a Conventional Twig namespaces section listing
  every auto-registered namespace and its source directory, and fills
  the previously missing metadata keys (asana, figma, drupal,
  web, styleguide) into the Per-template metadata table. The URL
  surface table now lists /styleguide/foundations, /styleguide/fields,
  and documents the whitelisted ?theme=light|dark query param on
  /render/*. The local-dev path repository snippet is rewritten to
  match the canonical mechanism from AGENTS.md (canonical: false +
  versions override + switch scripts).

Added

• New /styleguide/overview page (label „Přehled" / „Overview") —
  Components & Pages master index that lists every component and every
  page shipped by the consumer project, grouped by sidebar section
  (Základní prvky / Bloky / Gutenberg / Stránky), with a persisted
  „Zobrazit použití" / „Show usage" toggle (localStorage key
  sg-overview-show-usage) that reveals forward usage (page →
  components used) and reverse usage (component → where it's used) as
  clickable chips. A compact 4-column directory grid at the bottom
  lists everything alphabetically per section as a fast-jump. Renders
  directly in the SPA shell (NOT inside the iframe) so the visual
  chrome ships with the package; visuals are unified across consuming
  projects regardless of their own CSS. Data source is the existing
  /api/components + /api/pages payloads parsed by ComponentParser
  — no new backend endpoint, no new YAML metadata semantics. Reverse
  usage is built lazily into a Map<id, ids[]> on first access and
  then looked up in O(1).
• Styleguide now auto-registers the conventional Twig namespaces
  whenever the matching directory exists: @component, @macro,
  @page and @static under templates_path; @icons and @images
  under static_path (i.e. images/icons/ and images/ as siblings
  of templates/). Consumers no longer need to enumerate any
  $loader->addPath(__DIR__ . '/templates/component', 'component') or
  $loader->addPath(__DIR__ . '/images', 'images') lines in their
  static/index.php — the package walks both roots once at
  construction and wires the standard layout itself. Projects with a
  non-standard image root (or any extra namespace) can still use the
  new namespaces config key as <name> => <absolute path>; missing
  directories are silently skipped so a stray entry doesn't take the
  whole styleguide down. Re-running the constructor on the same env is
  a no-op via realpath()-based deduplication, which matters for
  projects that share one Twig environment across requests.

Changed

• The Fields drawer is redrawn as a four-column tree
  (Field / Type / Title / Description) with depth-indented child rows
  (└ glyph at depth > 0), a colour-coded Type pill per field-type
  family (array/object purple-pink, text blue, textarea indigo,
  image emerald, link orange, anything else neutral zinc), and a
  red-dot Required indicator with a localised footer legend. Default
  state stays collapsed; the trigger badge shows the recursive node
  count. Design rationale in
  docs/superpowers/specs/2026-05-20-fields-drawer-design.md.
• Styleguide::buildOwnTwig() (the pristine env built when the consumer
  omits the twig config key) now defaults autoescape: false alongside
  the existing cache: false + debug: true. Previously the env fell
  back to Twig's own default of autoescape: 'html', which meant every
  consumer that didn't pass its own Environment had to either accept
  HTML-mangled output from |typography / WYSIWYG / |raw-style filters
  OR pre-build a one-off env just to flip that single option. Both
  branches of the package's pristine-vs-provided-env contract now share
  the same project-wide defaults; consumers can drop the boilerplate
  new Environment(..., ['cache' => false, 'debug' => true, 'autoescape' => false]) block from their bootstrap if it was only there to override
  this one flag. Behavior is unchanged for consumers that pass an
  explicit twig Environment — the package never touches options on a
  provided env, it just attaches loaders. Consumers that need different
  pristine-env defaults can pass a twig_options config map — values are
  merged on top of the three defaults, so a partial override
  (['cache' => '…']) keeps debug and autoescape at the package's
  defaults. Projects that expose their styleguide outside trusted local /
  dev contexts and want Twig's XSS protection back on can opt in with
  'twig_options' => ['autoescape' => 'html'].
• BREAKING (URL): The /styleguide/overview URL now serves the new
  Components & Pages index above. The previous logo + colors +
  typography page has moved to /styleguide/foundations and its
  internal kind likewise became foundations in Router.php,
  Renderer.php, Styleguide.php, templates/foundations.twig (was
  templates/overview.twig) and the corresponding frontend route-type
  checks (stores/ui.js, components/preview.js, index.html,
  styleguide.js). The page's user-visible label was simultaneously
  renamed from „Přehled" / „Overview" to „Základy" / „Foundations"
  to reflect what the page actually shows — the foundational design
  layer beneath components — and to free up „Přehled" for the new
  overview index. The i18n key in frontend/public/locales/{cs,en}.json
  moved from nav.overview to nav.foundations; a fresh nav.overview
  key now carries the new label. Bookmarks pointing at the OLD
  /styleguide/overview will land on the new index page; the
  pre-rename meaning was only in production for the duration of the
  current [Unreleased] window so practical impact is limited to
  in-progress dev branches.
• CI workflows (tests.yml, release.yml, release-stamp.yml) bumped
  actions/checkout@v4 → actions/checkout@v5. The v4 line runs on Node 20, which
  GitHub started flagging as deprecated in Actions logs; v5 moves to
  Node 24. No behavior change in the workflows themselves — the bump
  exists only to clear the runtime-deprecation warning. Other actions
  (actions/cache@v4, shivammathur/setup-php@v2) are still on their
  current latest majors and were left alone.

Fixed

• Overview index restores the per-row external-link icons that the
  pre-redesign styleguide carried — Asana / Figma / Drupal / Web SVG
  badges fed from each component's parsed YAML metadata (asana:,
  figma:, drupal:, web:). Icons render in two places: the row
  header (full item, larger 28px badges) and every "Used in" / "Components"
  chip (decorated chip from the forward / reverse map, smaller 24px
  badges). _buildForwardMap and _buildReverseMap now copy the four
  link fields onto each chip, so the chip-level row needs no second
  store lookup. New linksFor(item) helper on the overview component
  returns the same {key, url, label}[] shape the per-component
  linkBar already uses above the iframe, so the four SVG <template>
  blocks stay structurally identical across both surfaces.
• /styleguide/foundations now ships its own Tailwind utility bundle.
  Consumer projects scan only their own templates/**/*.twig in their
  Tailwind v4 @source directives — the package's own
  templates/foundations.twig is in vendor/parisek/styleguide/templates/
  and therefore invisible to the consumer build. Without its layout
  utilities (h-32, max-w-48, min-h-32, prose-*, etc.) the
  foundations route rendered with broken sizing: the logo overflowed the
  card, swatches collapsed to zero height, body samples lost their
  responsive prose scale. The package now builds a dedicated
  dist/foundations.[hash].css from a new frontend/foundations.css
  Tailwind entry that explicitly @sources the foundations template;
  render-cell.twig links it alongside iframe.css only on the
  foundations route, after the consumer stylesheet so consumer overrides
  on shared classes still win. Consumers don't add any @source path of
  their own — pulling the new package version + running their existing
  composer update is enough.
• Per-component Fields drawer now actually renders for real-world
  components. The previous incarnation gated on Array.isArray(fields)
  but ComponentParser passes the YAML fields: map straight through
  as a PHP associative array (JSON object on the wire), so the drawer
  silently hid itself on every component with field metadata. The
  drawer now walks the nested map via DFS in JS (Alpine 3 templates
  can't self-recurse) and renders a flat, depth-tagged list — arbitrary
  nesting depth supported.

Pull Requests

• #7 — feat(preview): granular viewport presets + Custom px input + overview lock
• #9 — feat: Components & Pages overview index page + foundations route rename
• #10 — refactor(spa): overview redesign, iframe auto-fit, per-component fields drawer
• #11 — feat(styleguide): default autoescape: false in buildOwnTwig() pristine env
• #12 — feat(spa): per-component fields drawer — nested tree, dark chrome
• #13 — feat: dark mode for the styleguide chrome

Full Changelog: v0.1.3...v0.2.0