The problem, and what is aimed at

An application draws what it wants, and puts it where it wants. What it does not choose are the icons the framework draws in its own components — the arrow of a nav, the two of the accessibility controls, the boxes of a selector, the fourteen of a presentation. Those come from one set, in one place, and an application that wants others has to rewrite the components that hold them.

What the framework offers besides is one set, under one path, asked for by name. An application that needs two sets has no way to say that the same button is not drawn the same in both: several sets are several drawings of each icon its pages use, and there is one place to put them. One that owns a drawing of its own has no way to add it beside the others. And one whose icons are images rather than line drawings has no way in at all.

The question is therefore: how does a document show the icons that belong to it, without redrawing what it does not care about, and without losing what a local document, a dark mode or a screen reader ask of an icon.

What is aimed at: let an application bring its own icons, whole sets or a handful; let a document be read with the set that suits whoever reads it; keep what the framework holds today, an icon that follows the color of what surrounds it, on a document opened from a disk, without a server and without the internet; and ask an application for the drawings, and for nothing else.

What an application writes to get all that is on icons.html.

Expression of the needs

An application has icons that belong to it, and wants to show them. It does not want to redraw the ones the framework provides and that suit it. It therefore gives the icons it owns, and the framework gives the others.

What it gives is not one set: one of them is complete and the others are not. An application that shows an incomplete one wants the missing names answered by its own complete set, and not by drawings that are not its own. It says which of its sets answers for the others; what came with the tool answers last, and only what neither of them carries.

One application may need several sets: the same button is not always drawn the same way, and what tells one set from the next is its own business. It gives as many as it wants, each under a name, and the reader chooses the one the document is shown with. Changing that choice does not load the page again, and the choice holds from one page to the next.

The reader sees the icons wherever the document is opened, served or taken from a disk. He sees them whatever the mode and the theme he reads in, and at the size he reads the text at: a contrast mode writes the text larger, and an icon that stayed where it was would be small beside it, and harder to aim at when a button holds nothing else. And whoever does not see them is told what they stand for.

Nothing moves when a drawing arrives, and nothing moves when the set changes. The room is therefore declared by the place and not by the drawing, in both its dimensions, since an icon is not always square: a set of flags is not a set of arrows. A drawing of other proportions is held inside that room rather than stretched to it.

An icon may be asked for under a name that no set carries. The page holds and shows the rest, and the console names it, so that whoever wrote the page can correct it.

What is not shown is not sent, and what is going to be shown says the room it takes before it arrives. Both are asked by the RGESN, the French reference for the eco-design of digital services, as WCAG asks that an icon be told to whoever does not see it. Neither is an improvement here: they are conditions.

Elicitation of the needs

Six things are handled, and they are all that is handled.

I1. A name is what an icon is asked for by. It says what the icon stands for, never where it is drawn: the same name is answered by a different drawing from one set to the next.

I2. A drawing is what answers a name. Its form follows from the file it stands in: a line drawing, which takes the color of what surrounds it, or an image, which carries its own.

I3. A ground is what covers a surface: a texture laid on a plain background. It is named as an icon is, and answered the same way, but it designates nothing, and it is asked for by a surface and not by a place.

I4. A set is what holds drawings and grounds under names. It carries part of the names, or all of them, and says which ones it carries. One is the reference set, and answers what the others leave unanswered.

I5. The set in force is the one a document is read with. There is one at a time, and the reader chooses it.

I6. A name it does not carry goes down a chain of two: the fallback set, which the application names among its own, and then the reference set, which belongs to the framework. Either may be absent, and the chain is the same for every name.

Organisation of the needs

I10 Icons of an application

• I11 The author can declare a set of icons that belongs to the application.
• I12 The icons an application brings are shown in place of the ones that came with the tool.
• I13 The author is free to draw only some of the icons, the others being no less shown.
• I14 A name the shown set does not carry is answered all the same, by another set.
• I16 The author says which of the sets answers what the others leave unanswered. What that one does not carry either is answered last, by what came with the tool.
• I15 The author adds an icon by bringing its drawing, and writes nothing else.
• I17 The author can be told the names a set answers, so that a page lays out the drawings it can ask for without listing them by hand.
• I18 The author says where his set stands, wherever that is: beside the page, at the root of the site, or on another host. A set he brings has no reason to stand where the tool stands.

I20 Several sets

• I21 The author can declare several sets, each under a name.
• I22 The reader can choose the set the document is shown with.
• I23 One set is in force at a time, for the whole document.
• I24 The set in force is the same from one page of the document to the next.
• I25 The set in force changes without the page being loaded again.
• I26 A drawing is loaded only when it comes into what the reader sees. RGESN
• I27 A change of set loads again only the drawings the document is showing.

I30 What an icon is made of

• I31 The author can bring line drawings and images, of whatever the file they stand in, in one set. Grounds are I70.
• I32 A line drawing is shown in the color of what surrounds it.
• I33 An icon that carries its colors is shown as it is drawn.
• I34 The element that holds an icon declares the room it takes, in both its dimensions, before the drawing arrives. RGESN
• I37 An image carries the two dimensions the place declared, so that nothing waits for the file to know them. RGESN
• I38 A drawing whose proportions are not those of the place is held inside it, and never stretched.
• I35 Nothing moves around the icon when the drawing arrives.
• I36 An icon is drawn at the size of the text around it, and grows with it.

I70 Grounds

• I71 The author can bring grounds, each under a name, in the sets that carry the icons.
• I72 A surface is covered with the ground of the set in force.
• I73 A surface whose name the shown set does not carry is covered all the same, by the ground of another set.
• I74 What a ground stands for is never told: it stands for nothing.
• I75 Nothing moves around a surface when its ground arrives.
• I76 A surface is covered only while the reader sees it.

I40 Where the document is read

• I41 The reader can see the icons on a document opened from a disk, with no server.
• I42 Nothing is asked of the internet.
• I43 The reader sees the icons in every mode and every theme.

I50 What an icon says

• I51 The reader who does not see the icon is told what it stands for.
• I52 The icon itself is not read out.

I60 What is missing

• I61 Nothing is shown for a name no set carries.
• I62 That name is said in the console, for whoever wrote the page.
• I63 Everything else is shown, and the page holds.

Left for later: showing two sets at the same time, so that they can be compared, and adding a set once the page is open.

What was set aside

These were considered and decided against. They are not missing.

MCC — who exchanges what

The organisation is the document, and what runs it. Two external actors exchange with it, and it is cut into two internal ones.

Flows 1 to 4 come from outside and become the external events of the MCT. Flows 5 and 6 leave it and are its results. Nothing else crosses: nothing is asked of a server, nothing is stored, nothing is sent back. I42

MCD — what the data are made of

Five entity classes, the identifier of each one written with a #.

R1 is an aggregation: a content is named inside the set that carries it, and two sets name a content the same way without naming the same content. The set is the aggregating class, the content the aggregated one.

R2 leaves a place with no content, which is the case I61 asks to treat: a name no set carries answers nothing, and the room stays empty. R4 says the same of a surface, which keeps the plain background it had.

Two things are computed, never held: which content answers a place or a surface, which follows from R3 and R1 and changes when the reading is shown with another set I25; and whether a place or a surface is in view, which is what triggers the question I26 I76.

The constraints

On roles. SET takes part in R1 and R3, CONTENT in R1, R2 and R4. A content answers a place or covers a surface, never both, which is an exclusion on roles between R2 and R4: its kind says which of the two it is. Nothing else — no totality, no subset, no equality.

On relations. A content that answers a place is carried by a set, which would be a subset constraint from R2 to R1; the cardinality (1,1) of R1 already says it, and the arrow would add nothing. The same holds of R4. No exclusion, no equality between relations.

What the formalism does not carry is said here. C3 is the one that decides: it restricts R2 by R3, and no arrow between two relations says that.

That is why which drawing answers a place is computed and never held: it follows from R3, then from R1, and it changes when the reading is shown with another set.

MCT — the events and the operations

What has to be done, and on what. Not when, not how, not where.

Nothing is read here: a set says what it carries, and OP1 believes it. That is what lets OP3 answer without asking. I6

A set that was never declared is a set nobody named: the set in force does not change for it. I23

OP3 is ininterruptible for one demand: a set put in force while a content is being read is taken into account after, by E5, and not during. Nothing moves around what was asked for, the room of a place having been declared before and a surface keeping the one it has. I34 I75

What the content is decides what OP3 produces, and nothing else does: a drawing is shown at a place, a ground is laid on a surface, and neither is ever the other. C8

OP4 answers nothing of its own: it gives OP3 its event back, and for what is in view only. What is not seen is answered when it is seen. I27

One process, four operations. E1 and E2 open it, E3 comes as often as the reader asks, E4 as often as the reading moves, and E5 only when OP2 changes what was in force.

MOT — when, where, and by whom

The operations of the MCT, cut into functional procedures, each triggered by one event.

PF0 is what the MCT does not show: a document read where nothing serves it cannot go and get anything, so what it will need has to be gathered into it beforehand. That happens elsewhere, at another time, and under the responsibility of the author — which is why a set meant for such a document is gathered as the reference set is. I41

Everything else happens where the document is read. Nothing is done elsewhere, and nothing is kept from one opening to the next: PF1 and PF2 run again at every opening, and give the same result.

PF2 and PF3 are one operation cut in two, because two events trigger it and two are in charge: the system at the opening, the reader afterwards. What they produce is the same, one set in force. I24

PF4 comes as often as the reading moves, and never before PF2: a demand answered without a set in force would be answered twice. Its resources differ according to whether the document is served or not, and it is the only procedure where that difference is seen.

MLD — the tables

Each entity class becomes a table, its identifier becomes the key.

R1 is an aggregation: the aggregated class takes the key of the aggregating one, so CONTENT holds the name of its set, and the two together tell one content from another. Two sets carry a content under one name without carrying the same content.

R3 has a low cardinality on the side of READING, which is (1,1): the table READING takes the key of SET, under the name of what it says — set_in_force.

R2 and R4 are translated by nothing. Which content answers a place, and which one covers a surface, are computed from the set in force and from what the sets carry: a column would hold an answer that changes as soon as the reading is shown with another set, and would have to be emptied at every change. C3

Not in the tables either: whether a place or a surface is in view. It is read where the document is read, and it changes as the reading moves.

MPD — where each table stands

Here the tool is named, and not before: Whakerexa answers what the needs ask for, and it is the one that is extended. There is no database — the tables are borne by the document, by what runs it, and by what is built before it is read.

Two things the tables do not hold are read from the browser: whether a place is in view, which IntersectionObserver answers, and the size of the text around an icon, which the font size of the element answers.

The reference set is wexa_statics/icons/mono-svg/. What a set says it carries is what makes the chain work with no request: on file:// a request would never be answered, and on http it would cost one for every name a set does not carry, at every step of the chain. I6

MOpT — where the code goes

Under wexa_statics/js/, one file per class, as the framework already writes them. The module that gathers is a script of scripts/, run before a release, beside the one that builds the bundle.

SVGIconsManager answered for reading and for placing at once, and for one set only. It is what the modules above took apart, and it is gone.

The decisions of the tool

What the levels above do not decide, and what the code will show. They belong here: they are choices about the tool, and they could not be made before it was named.

D1. One package holds what customises the look. The manager of the themes and the one of the sets hold the same kind of state — a name in force, read in the address and written back — and they answer the same need on two matters. They are written together rather than apart.

D1b. The manager is held under Wexa.iconsets. Wexa.icons is the name of the older manager, which the components of the framework still call: taking it would leave them without icons. The two names live side by side until D2 is done, and D2 is a broken promise for whoever calls Wexa.icons.get().

D2. What reads and what places are taken apart. SVGIconsManager did both, for one set. Reading changes when a document is served or not; placing changes when a content is a line, an image or a ground. They do not change for the same reasons, so they are not one class. The older one is removed, and Wexa.icons is the new manager: what it holds of the old are get() and inject(), which the components of the framework call.

D3. A place declares its room counted on the font size, in calc(var(--font-size) * n) as the framework counts every size, and in both dimensions. One declaration holds three needs: the room kept before the image arrives I34, the size that follows the text I36, and the two dimensions an image is given so that nothing waits for the file to know them I37. A drawing of other proportions is held inside that room I38: the place is what does not change from one set to the next, so it is the place that decides the shape.

D4. A set is declared on the loader, beside the themes, and not in a call written in every page. A page says what it brings where it already says what it loads, and names there the set that answers for the others.

D7. A set is declared in one line: its name, its place, its files. The name is what stands before the first colon and the files what stands after the last one, so that the place between the two keeps the colon of an address that carries a host. The files are written and not asked for: it is what lets a name fall back with no request at all, on a document read from a disk as on one that is served I41 I42.

D8. The names a set answers are computed, never held. They follow the chain of C3 and change with the set in force, exactly as the drawing that answers a place does. A page that lays them out asks for them when it lays them out I17.

D9. The demand is carried by the element that means something — a button, a link, a heading — and never by an element written for the icon alone. What the icon stands for is said by that element and not by the drawing I51: an element written for the drawing alone would carry something that names nothing, and a reader who does not see it would be told nothing. It is also what keeps the drawing out of the reading I52, the element that holds it being what is announced.

D6. The chain has two links and no more. A set that answers for the others, then the reference set. Letting each set name the one it falls back to would make a chain of any length, which nobody asked for, and which would have to be walked at every name and guarded against cycles.

D5. What a set carries is gathered into the document at build time, by a tool the author runs. It is the only way a document read with nothing serving it can answer a name. Only the line drawings are gathered — an image is answered by its address, which a document finds beside itself.

D5b. What is gathered is written on the namespace of the framework, as Wexa.gatheredIcons, and not under a name of its own. The style guide of the project asks that a global be avoided; the framework already holds one, Wexa, and a second would be one too many. The file that carries the drawings is loaded before Whakerexa is there, so it makes that object if it has to and wexa.js adds to what it finds. What an older build left under a name of its own is read as well: the decision changes where the list is written, not what a document already carrying one can do.

It is a script and not a file of settings. A browser refuses fetch() on a file:// address, and that address is the one case this file exists for I41 I42: a .json could not be read there, while a script is run. Served, nothing of this is needed — a drawing is asked for when a place demands it — so a file of settings would fail where it would be useful, and add a request where it would not.

It is a list and not a call on a class: a file loaded by a page cannot know when the framework will be there, and a list waits without asking anything. Its name says a list and not a constant — the page fills it, the loader empties it. And a list is all it is, so an author whose tools are his own writes it as he likes: nothing of the framework runs to produce it, and nothing of it is asked at the moment it is read.

The classes that carry the data

They come from the MLD, one class per table, and they are set at construction. What they give back is a string or a copy.

PLACE and SURFACE become one class: they differ by what answers them, which C8 says is the kind of the content, and by nothing they hold themselves. READING becomes no class at all — the set in force is a name, held by the one that changes it.

The classes that do the work

One per module of the MOpT, and each one is the only one that knows what it knows.

What each one promises: IconSets reads nothing and asks nothing, which is what makes it testable without a document; IconReader is the only one that goes and gets a content; IconPlacer is the only one that changes the document shown; IconManager is the only one that writes a try.

The states of a demand

A change of the set in force takes an answered demand back to watched, and only those in view. An unanswered one is not tried again under the same set: what a set carries it has already said. C4

The sequence when the page opens

1. The page declares its sets; IconSets holds them, the one that answers for the others, then the reference set: that is the chain.
2. IconChoice reads the address, then what the page names, then falls back on the first set of the chain.
3. IconWatcher is given the demands of the document.
4. A demand comes into view: IconSets says which set answers its name.
5. IconReader reads the content; IconPlacer puts it where it was asked for.
6. IconRegister holds the demand.
7. The reader chooses another set: IconChoice says so, IconRegister gives back what is in view, and step 4 begins again for those.

Step 1 before step 2, and step 2 before step 4: a demand answered before a set is in force would be answered twice, and would move what is around it.

The error policy

Exceptions are raised at the lowest level and caught at the highest. An error must never do worse than the absence of the program: without it a page shows no icon and reads all the same.

How to read them

+ public, - private, / derived and never held, {readOnly} does not change after construction, {ordered} the order matters. pre is what has to be true on the way in, and what the operation does not check; post is what the caller can count on.

Two rules hold everywhere: a name that answers nothing gives back an empty string, an empty array or an empty map, never null; and the fields of a data class are set at construction and give back a copy.

The data classes

carries() answers from what was declared, never from what exists: that is the whole of decision 2.

The working classes

IconSets.setFor() is the whole of the fallback, and it reads nothing: it is the one operation that decides, and the one that is tested without a document.

Three exception classes: IconError, the mother, raised by nobody; NoSetAtAll, raised when not one set was declared; UnreadableContent, raised by IconReader.read(). IconManager is the only one that writes a try.

Without a document

IconSets decides the whole chain and reads nothing, so every rule of it is checked without opening anything: a name the set in force carries comes from that set; a name it does not carry comes from the set that answers for the others; a name neither carries comes from the reference set; a name none of the three carries comes back as nothing; a set that answers for itself answers as if it answered for nothing; a set declared twice keeps the first and says so. C1, C2, C3, C10

IconSet.carries() answers from what was declared and never from what exists, which is checked by declaring names no file stands behind: the answer is the same. That is the test that holds decision 2, and it would pass on a machine with no icon at all.

IconChoice reads and writes one name: a set that was never declared does not become the set in force; putting the one already in force changes nothing and says so; the name is found again in the address. I23 I24

IconRegister gives back what it holds, and only what is in view. I27

With a document

IconPlacer is checked on written markup: a line drawing takes the color of what surrounds it and an image keeps its own I32 I33; a ground covers a surface and no place [C8]; what surrounds a demand has the same size before and after, and the same again with a drawing of other proportions I35 I38 I75; an image carries the two dimensions the place declared I37; and clear() leaves the room where it was.

IconWatcher is checked on a document taller than one screen: a demand out of view is not announced, and is announced when the reading reaches it. I26 I76

IconManager is checked on what must not break the page: not one set declared, a name nobody carries, a content that cannot be read. It never raises, the page holds, and the console has said the name. I61 I62 I63

Where

In wexa_statics/js/tests/, one file per class, run by tests.html, as the framework already tests. The tests of the first section are the ones written first: they are the whole of the decisions, and they need nothing to run.