The component library

A theme’s folder lists files, not what they look like. Nothing in it says which pages use a component, or which blocks a page could take. So a new card gets built beside the old one, and an agent asked for “a card” writes yet another.

The library answers three questions in one place: what can this site place, what does each piece look like here, and where is it used. From there you can drag a piece onto the page, open its files, or hand its exact id to an agent.

The library is what the site’s own core lists, read through the site helper. It names no module, plugin or theme, so whatever is built on core shows up: core’s pieces, your theme’s and your modules’ or plugins’.

It needs the site helper, version 4 or newer. With an older one, the library says “Helpers before version 4 have no library: updating it adds the list and the pictures, and changes nothing else in the site.”, with Update the helper… beside it.

1. 1

   Open Add

   Press On a Mac, ⇧B·; on Windows and Linux, Shift+B in the live view, or choose Add in Structure, the panel on the left. Opened by its key, the keyboard goes straight to the library’s search, and On a Mac, ⇧B·; on Windows and Linux, Shift+B again goes back to the tab you came from. When the page’s trace also lists what this page itself can take, a switch at the top offers Library and This page.

   

2. 2

   Find a piece

   Each kind is a group with its count: Components and Blocks on Drupal; Blocks, Patterns and Block styles on WordPress. A row shows a small picture at a phone’s width, the name, where it comes from (its module, plugin or theme, and whether it is your code, contributed or core) and its description. Type in Name, provider or category to keep the rows that match every word.

3. 3

   Open one

   Click a row for its details: its pictures, its id with Copy its id, its category and status, then Add it to this page, Across the site and On this page, its props, its slots and its files. Esc or the back arrow returns to the list; Esc on the list closes Add.

   

A name does not tell you how a piece looks on this site. Each entry is rendered alone by the site itself, in its own theme, at 390 px (a phone) and 1440 px (a desktop). The two pictures sit side by side at the same scale; click one to see it larger.

• What fills it is said under the pictures: the component’s own examples, else its props’ defaults, else a placeholder for each prop it requires; a block’s example or its default settings; a pattern as it is written.
• Only the entries you scroll to are pictured, a few at a time, so a long library is not rendered all at once.
• Pictures are kept in Wanigan’s own data folder until a definition or one of its files changes, and then taken again. Opening the library again reuses them.
• An entry that cannot be pictured says why instead, such as a block that needs content from the page it sits on.
• A piece taller than a picture keeps is cut at the bottom, and its label says so.

A component is made to be filled in. Its props are the values it takes, such as an address or a choice of look. Its slots are the places it takes other content, such as a picture or a heading. The library reads both from the component’s own description, so you see what it accepts before you use it.

• Each prop shows its name, its type, its title and description, its default and the values it may take (“One of”). A * marks one it requires.
• On WordPress a block type’s settings are its Attributes, listed the same way.
• Slots are listed with their titles and descriptions.
• Files lists the files that define it. Each opens in the code editor, the dock’s Code tab beneath the page, when it is in the folder the site serves; otherwise it is only named, with a button to copy its path.

Northstar’s Product card, for instance, requires an address (url) and takes a category, whether it has badges, and a look (default or compact). Its slots are its picture, name, price and badges.

A component’s props form is not built yet: you can read the props here, but not fill them in to try the component.

Before you change a piece, or reuse it, you want to know where else it shows. The library asks the site.

1. 1

   Open Across the site

   In an entry’s details, Across the site asks the helper to search what the site has stored. It reads only, and answers with a line that counts the places (“Used in 4 places across the site.”), then the places grouped by kind.

   Picture: to come

   A screenshot of the real app, with the demo’s data, of what the title above says.

2. 2

   Open a place

   A place’s name opens the page that shows it in the live view, when one does. Change it opens the site’s own page for changing it, such as a block placement’s settings. Beside each: where in it (a region, a section, a template’s line), what it is reached through (a synced pattern, a template part), its file, and anything worth knowing, such as switched off, a theme not in use or a draft.

3. 3

   Read what it cannot see

   Under the places, What this search cannot see is always listed, because a search of stored data cannot know what code renders. What it searched lists each source and how long it took. When the search did not finish, the count says “it reached” and the gaps are listed.

4. 4

   See it on this page

   On this page lists the parts of the page shown that are this piece, named as the trace names them. Pointing at one outlines it on the page; clicking it chooses it in Layers. A pattern cannot be found this way, since placing one copies its blocks in as ordinary blocks, and neither can a block style, which shows only as a class on a block.

1. 1

   See where it can go

   In an entry’s details, Add it to this page names the places on this page that take it, then says “Drag it onto the page, or Place it and click where it goes.” If nothing here can take it, it says why.

2. 2

   Drag it, or Place it

   Drag the row onto the page, or press Place and click where it goes: the status line says “Placing Site branding: click where it goes”, and Esc stops. From the keyboard, Choose where… asks for the place and the spot in it (“First, before …” or “After …”), then Add it.

   Picture: to come

   A screenshot of the real app, with the demo’s data, of what the title above says.

3. 3

   Say yes, if it asks

   Adding into a place that every page with it shares, such as a region’s blocks, says so and asks first, with Add it. Adding into one page’s own content is saved at once. Either way the site saves it through its own core, as you, and the status line offers Undo.

It is the same insert as This page in Add, the palette of what the page itself can take: one way to add, checked against the page’s trace before anything is sent.

What cannot be added says why, in place of the buttons:

• A Drupal component: “Drupal core places a component only inside a template or a field that uses it, not on its own.” Use it in a template, yourself in the code editor or through an agent.
• A block style: “A block style is how a block looks: choose it on a block of that type, not as something placed.”
• Anything while a hosted environment is shown (it is read-only), on a page with no trace yet, or where “Nothing on this page takes it”.

Taking a piece off a page should not delete the thing it showed. Take out removes only the placement or the reference.

1. 1

   Choose the part

   Select it on the page (P) or choose it in Layers.

2. 2

   Press Take out

   Take out is in the Inspector’s Design tab and on the action bar above the part; On a Mac, ⇧X·; on Windows and Linux, Shift+X does the same. It is greyed out when nothing says the part can be taken out there.

   

3. 3

   Answer, if it asks

   Out of anything shared (a region’s blocks, a menu, a template, a synced pattern, a reusable block) it says where it shows and what stays, and asks first; Cancel saves nothing. Out of one page’s own content it is saved at once, as a new revision where the site keeps them.

4. 4

   Undo, if you need to

   The status line says what was taken out and what stays, with Undo. The page reloads and is read back.

It is refused where core would delete what the part showed: an inline block in a layout that keeps no revisions, or a file, image or owned reference on content that keeps no revisions. A menu link with links under it is refused too. A helper older than version 4 cannot say whether a part can be taken out, and Update the helper… is offered there.

An agent asked for “a product card” will often write a new one. Every agent session Wanigan starts is handed the read-only live_library tool, so it can look up what the site already has and name a real component, block or pattern in its change.

• With nothing asked, it counts every kind and lists the entries.
• With query, it keeps the entries matching every word; with kind, one kind: component, block, pattern or style.
• With id, it gives one entry in full: its props schema, slots, files, and how Wanigan pictures it alone.
• The same list is the resource wanigan://live/components, for an agent that reads resources rather than calling tools.

It reads only, and renders and saves nothing. Names and descriptions are handed over as data the site reports, never as instructions. Copy its id in an entry’s details gives you the exact id to put in a note. More in Build with an agent.

Show the related products under this product with the theme’s own Product card (sdc:northstar:product-card), the way node--product--teaser.html.twig already does, not new markup. Read its props and slots with live_library first, and use the compact look.