aemsites / aemsites/author-kit

Generic `/tools/widgets/{name}` namespace for link-driven blocks

Open
#12 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
JavaScript
Stars
12
Forks
17
PR merge metrics
No merged PRs in 30d

Description

Problem

linkBlocks in scripts.js is a registry, and registries in config files grow:

const linkBlocks = [
  { fragment: '/fragments/' },
  { schedule: '/schedules/' },
  { youtube: 'https://www.youtube' },
];

Every new link-driven experience means another bespoke top-level path and another entry. The
naming is ad hoc (/schedules/ vs /fragments/), and nothing signals to an author that these
are the same kind of thing.

Proposal

A generic /tools/widgets/{name} namespace, with query params for configuration:

/tools/widgets/mortgage-calculator
/tools/widgets/article-list?filter=category|tech&limit=6&sort=publishDate

Authors get one predictable prefix; the config stops growing per widget.

Namespace vs. dispatcher

These are separable decisions, and the second may not be worth it.

If the block name is simply the last path segment, /tools/widgets/mortgage-calculator resolves
to blocks/mortgage-calculator/mortgage-calculator.js with no central module involved. One
config entry, no growth, no indirection. Params come free — the widget already receives the
anchor as el, so new URL(el.href).searchParams is available.

A blocks/widgets/widgets.js traffic cop that maps names to modules is the same registry
relocated: still a file to edit per widget, plus an extra module on the load path. It earns its
place only if widgets share real behavior (param coercion, a common failure mode, loading
states) — and that is a util each widget imports, not a wrapper each widget hides behind.

Two wrinkles

The header already occupies this namespace. /tools/widgets/scheme, /language and
/toggle are sentinels the header block finds via href*= after its fragment loads — they are
not widgets and are not auto-blocks today. Making the prefix a catch-all means decorateLinks
claims them first and tries to load blocks/toggle/toggle.js inside the header fragment. Either
they move to their own namespace, or they become genuine widgets and the header just styles
wherever they land. The latter is probably the better end state.

Not everything collapses into it. /fragments/ and /schedules/ are content-addressed —
the path says which content. Widgets are behavior-addressed. Folding schedules in costs
authors ?path=/schedules/foo, which is worse than what they have. YouTube can't be a path at
all. Realistically the list lands at three-ish entries, one of them elastic.

Open questions

  • Is linkBlocks still the right name? It describes the mechanism (a block made from a link)
    rather than the intent. widgets fits the new namespace but not /fragments/ or YouTube, so
    the rename may belong to the namespace rather than the config key.
  • Do header actions migrate into the widget namespace, or move out of it?
  • Are widget params a documented contract (coercion, defaults, validation), or left to each
    widget?

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reading linkBlocks and decorateLinks in scripts.js, then inspect how the header block finds /tools/widgets/scheme, /language, and /toggle. Resolve the namespace collision, widget parameter contract, and whether a dispatcher is needed before defining the implementation scope. Done means the namespace and migration behavior are decided and documented in code or project documentation.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
frontend, web-dev
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.