aemsites / aemsites/author-kit
Generic `/tools/widgets/{name}` namespace for link-driven blocks
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
linkBlocksstill the right name? It describes the mechanism (a block made from a link)
rather than the intent.widgetsfits 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
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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