Merge branch 'main' of github.com:devforth/adminforth

Author: yaroslav8765

adminforth/design/system-concepts.md

@@ -9,7 +9,7 @@ Rules for the AdminForth UI (the "Hairline" theme). States and variants of every
 - Keep the token list short. Reuse a token with the same role before adding one: muted icons and secondary text `InputIconColor`, faint text and empty values (`-`) `InputPlaceholderText`, subtle fill `SecondaryDarken` / `SecondaryLighten`, page dimming behind dialogs, modals and drawers `Scrim` (a photo lightbox stays `bg-black/*`, it is dark in both themes), a softer variant of a token is its opacity modifier (`stroke-lightPrimary/50`). Add a token for a new role, not for a new component, always as a `light*` / `dark*` pair.
 - Statuses use `Success`, `Warning` and `Danger` tokens: the base one for text and icons, `*Soft` for the background, `*Border` for the border. Badges, alerts, toasts and diffs take them, e.g. `bg-lightSuccessSoft text-lightSuccess border-lightSuccessBorder`.
 - Gray ground, white surfaces, 1px hairline borders. Shadows only on layers that float above the page: popovers, menus, dialogs.
-- One ink (near-black) primary button for the main action of a screen, everything else is `secondary`, destructive actions are `danger`. The accent color is the `primary` token: links, focus rings, selection, active states.
+- One ink (near-black) primary button for the main action of a screen, everything else is `secondary`, destructive actions are `danger`. The accent color is the `primary` token: links, focus rings, selection, active states. An app which wants its brand color on the primary button aliases the `Buttons*` tokens to `Primary` in `customization.styles` (see the branding docs); core and plugins keep styling a button with the `Buttons*` tokens, never with `Primary`.
 - Fonts are Geist and Geist Mono (`@fontsource-variable/*`, OFL), the default radius is 6px (`rounded-default`).
 - Controls are 34px high: buttons, icon buttons, inputs, selects, date pickers and the header controls (theme toggle, avatar, plugin buttons). Small buttons (`size="sm"`) and the pagination of tables are 28px.
 - Focus ring is 3px of the `FocusRing` token. Buttons, checkboxes and toggles show it only on keyboard focus (`focus:outline-none focus-visible:ring-[3px]`), so a mouse click leaves no ring. Text fields show it on any focus (`focus:ring-[3px]`), the user types there next. A clickable element is a `<button>`, not a `<span>` or `<div>` with `@click`, so it gets keyboard focus at all.

adminforth/modules/styleGenerator.ts

@@ -314,34 +314,40 @@ export class StylesGenerator {
       return plainCustomStyles;
     }
 
-    private changeAlias(str:any, mergedStyles:any){
-      const {aliasMatch,opacityMatch,darkenMatch,lightenMatch, inverseMatch} = parseColorForAliases(str);
+    // a token may alias a token which is itself an alias further down the list, so the target is resolved first;
+    // `chain` is the tokens being resolved above this one and catches a cycle such as a -> b -> a
+    private resolveColor(key: string, colors: Record<string, string>, chain: string[] = []): string {
+      const { aliasMatch, opacityMatch, darkenMatch, lightenMatch, inverseMatch } = parseColorForAliases(colors[key]);
       if (!aliasMatch) {
-        return str;
-      } else {
-        const alias = aliasMatch[1];
-        let opacity = opacityMatch ? parseFloat(opacityMatch[1]) : 1;
-        const color = mergedStyles[alias];
-        if (darkenMatch) {
-          return darkenRGBA(createRGBA(color, opacity))
-        }
-        if (lightenMatch){
-          return lightenRGBA(createRGBA(color, opacity))
-        }
-        if (inverseMatch){
-          return inverseRGBA(createRGBA(color, opacity))
-        }
-        return createRGBA(color, opacity);
+        return colors[key];
       }
-    }  
-  
-    mergeStyles() {
-      let mergedStyles = deepMerge(this.defaultStyles, this.generatePlainStyles(this.styleConfig));
-      let colors = mergedStyles.colors;
-      Object.entries(colors).forEach(([key,value])=>{
+      const alias = aliasMatch[1];
+      if (!(alias in colors)) {
+        throw new Error(`Styles color ${key} aliases unknown token ${alias}`);
+      }
+      if (alias === key || chain.includes(alias)) {
+        throw new Error(`Styles color alias cycle: ${[...chain, key, alias].join(' -> ')}`);
+      }
+      const opacity = opacityMatch ? parseFloat(opacityMatch[1]) : 1;
+      const color = createRGBA(this.resolveColor(alias, colors, [...chain, key]), opacity);
+      if (darkenMatch) {
+        return darkenRGBA(color);
+      }
+      if (lightenMatch) {
+        return lightenRGBA(color);
+      }
+      if (inverseMatch) {
+        return inverseRGBA(color);
+      }
+      return color;
+    }
 
-        colors[key] =  this.changeAlias(value,colors)
-      })
+    mergeStyles() {
+      const mergedStyles = deepMerge(this.defaultStyles, this.generatePlainStyles(this.styleConfig));
+      const colors = mergedStyles.colors;
+      Object.keys(colors).forEach((key) => {
+        colors[key] = this.resolveColor(key, colors);
+      });
       return mergedStyles;
     }
-  }
+  }

adminforth/spa/src/afcl/Button.vue

@@ -5,7 +5,7 @@
     :disabled="props.disabled"
     :class="buttonClasses"
   >
-    <Spinner v-if="props.loader" class="w-4 h-4 text-lightButtonsText dark:text-darkButtonsText fill-lightPrimary dark:fill-darkPrimary" />
+    <Spinner v-if="props.loader" class="w-4 h-4" />
     <!-- the spinner takes the place of the icon in a square button -->
     <slot v-if="!(props.iconOnly && props.loader)"></slot>
   </button>

adminforth/spa/src/afcl/JsonViewer.vue

@@ -21,7 +21,9 @@
       </div>
     </teleport>
   </div>
-  <div v-else ref="viewerEl" class="afcl-json-viewer group relative flex items-start gap-2 font-mono text-xs leading-5">
+  <!-- the line width comes from the measured width of the viewer; inline-size containment keeps that width from depending on the
+       lines, otherwise in a shrink-to-fit parent (a flex-wrap item, a cell of an auto table) every re-wrap resizes the parent and loops -->
+  <div v-else ref="viewerEl" class="afcl-json-viewer group relative flex items-start gap-2 font-mono text-xs leading-5 [contain:inline-size]">
     <span ref="charEl" class="invisible absolute" aria-hidden="true">0</span>
     <div class="min-w-0">
       <JsonViewerNode :value="value" :depth="0" :last="true" :expandDepth="expandDepth" :lineWidth="lineWidth" />

adminforth/spa/src/afcl/Spinner.vue

@@ -1,8 +1,9 @@
 <template>
-    <div role="status">
-        <svg aria-hidden="true" class="text-lightProgressBarUnfilledColor animate-spin dark:text-darkProgressBarUnfilledColor fill-lightPrimary dark:fill-darkPrimary" viewBox="0 0 100 101" fill="none" xmlns="http://www.w3.org/2000/svg">
-            <path d="M100 50.5908C100 78.2051 77.6142 100.591 50 100.591C22.3858 100.591 0 78.2051 0 50.5908C0 22.9766 22.3858 0.59082 50 0.59082C77.6142 0.59082 100 22.9766 100 50.5908ZM9.08144 50.5908C9.08144 73.1895 27.4013 91.5094 50 91.5094C72.5987 91.5094 90.9186 73.1895 90.9186 50.5908C90.9186 27.9921 72.5987 9.67226 50 9.67226C27.4013 9.67226 9.08144 27.9921 9.08144 50.5908Z" fill="currentColor"/>
-            <path d="M93.9676 39.0409C96.393 38.4038 97.8624 35.9116 97.0079 33.5539C95.2932 28.8227 92.871 24.3692 89.8167 20.348C85.8452 15.1192 80.8826 10.7238 75.2124 7.41289C69.5422 4.10194 63.2754 1.94025 56.7698 1.05124C51.7666 0.367541 46.6976 0.446843 41.7345 1.27873C39.2613 1.69328 37.813 4.19778 38.4501 6.62326C39.0873 9.04874 41.5694 10.4717 44.0505 10.1071C47.8511 9.54855 51.7191 9.52689 55.5402 10.0491C60.8642 10.7766 65.9928 12.5457 70.6331 15.2552C75.2735 17.9648 79.3347 21.5619 82.5849 25.841C84.9175 28.9121 86.7997 32.2913 88.1811 35.8758C89.083 38.2158 91.5421 39.6781 93.9676 39.0409Z" fill="currentFill"/>
+    <!-- accent arc on a quiet track; inside an AFCL button both are drawn in the text color of the button (index.scss) -->
+    <div role="status" class="af-spinner">
+        <svg aria-hidden="true" class="animate-spin" viewBox="0 0 100 101" fill="none" xmlns="http://www.w3.org/2000/svg">
+            <path class="af-spinner-track fill-lightProgressBarUnfilledColor dark:fill-darkProgressBarUnfilledColor" d="M100 50.5908C100 78.2051 77.6142 100.591 50 100.591C22.3858 100.591 0 78.2051 0 50.5908C0 22.9766 22.3858 0.59082 50 0.59082C77.6142 0.59082 100 22.9766 100 50.5908ZM9.08144 50.5908C9.08144 73.1895 27.4013 91.5094 50 91.5094C72.5987 91.5094 90.9186 73.1895 90.9186 50.5908C90.9186 27.9921 72.5987 9.67226 50 9.67226C27.4013 9.67226 9.08144 27.9921 9.08144 50.5908Z"/>
+            <path class="af-spinner-arc fill-lightPrimary dark:fill-darkPrimary" d="M93.9676 39.0409C96.393 38.4038 97.8624 35.9116 97.0079 33.5539C95.2932 28.8227 92.871 24.3692 89.8167 20.348C85.8452 15.1192 80.8826 10.7238 75.2124 7.41289C69.5422 4.10194 63.2754 1.94025 56.7698 1.05124C51.7666 0.367541 46.6976 0.446843 41.7345 1.27873C39.2613 1.69328 37.813 4.19778 38.4501 6.62326C39.0873 9.04874 41.5694 10.4717 44.0505 10.1071C47.8511 9.54855 51.7191 9.52689 55.5402 10.0491C60.8642 10.7766 65.9928 12.5457 70.6331 15.2552C75.2735 17.9648 79.3347 21.5619 82.5849 25.841C84.9175 28.9121 86.7997 32.2913 88.1811 35.8758C89.083 38.2158 91.5421 39.6781 93.9676 39.0409Z"/>
         </svg>
         <span class="sr-only">{{ $t('Loading...') }}</span>
     </div>

adminforth/spa/src/components/ThreeDotsMenu.vue

@@ -57,7 +57,7 @@
           />
           <Spinner
             v-if="actionLoadingStates[action.id!]"
-            class="w-4 h-4 text-lightSkeletonBackgroundColor dark:text-darkSkeletonBackgroundColor fill-lightListTableText dark:fill-darkListTableText"
+            class="w-4 h-4"
           />
           {{ action.name }}
         </span>

adminforth/spa/src/index.scss

@@ -33,6 +33,12 @@ body {
   box-shadow: 0 1px 1px rgb(24 24 27 / 0.05);
 }
 
+// a spinner inside a button is drawn in the text color of the button, so it reads on ink and on a brand color alike
+.afcl-button .af-spinner, .afcl-link-button .af-spinner {
+  .af-spinner-arc { fill: currentColor; }
+  .af-spinner-track { fill: currentColor; opacity: 0.2; }
+}
+
 *{
   -moz-user-select: none;
 }

adminforth/spa/src/views/ListView.vue

@@ -62,7 +62,7 @@
               class="w-4 h-4 transition duration-75"></component>
               <Spinner
                 v-if="bulkActionLoadingStates[action.id!]"
-                class="w-4 h-4 text-lightSkeletonBackgroundColor dark:text-darkSkeletonBackgroundColor fill-lightListTableText dark:fill-darkListTableText"
+                class="w-4 h-4"
               />
             {{ `${action.label} (${checkboxes.length})` }}
             <div v-if="action.badge" class="inline-flex items-center h-[1.125rem] px-1.5 ml-1 rounded-full bg-purple-600 text-white text-[11px] font-semibold">
@@ -85,7 +85,7 @@
               class="w-4 h-4 transition duration-75"></component>
               <Spinner
                 v-if="customActionLoadingStates[action.id!]"
-                class="w-4 h-4 text-lightSkeletonBackgroundColor dark:text-darkSkeletonBackgroundColor fill-lightListTableText dark:fill-darkListTableText"
+                class="w-4 h-4"
               />
               {{ `${action.name} (${checkboxes.length})` }}
           </Button>

adminforth/spa/src/views/ShowView.vue

@@ -18,7 +18,7 @@
         class="h-[2.125rem] text-lightListViewButtonText dark:text-darkListViewButtonText px-3"
         variant="secondary"
       >
-        <Spinner v-if="isFetchingNextPage" class="w-4 h-4 text-lightSkeletonBackgroundColor dark:text-darkSkeletonBackgroundColor fill-lightListTableText dark:fill-darkListTableText" />
+        <Spinner v-if="isFetchingNextPage" class="w-4 h-4" />
         {{ $t('Next') }}
       </LinkButton>
 
@@ -44,7 +44,7 @@
               />
               <Spinner
                 v-if="actionLoadingStates[action.id!]"
-                class="w-4 h-4 text-lightSkeletonBackgroundColor dark:text-darkSkeletonBackgroundColor fill-lightListTableText dark:fill-darkListTableText"
+                class="w-4 h-4"
               />
               {{ action.name }}
             </Button>

dev-demo/index.ts

@@ -106,8 +106,16 @@ export const admin = new AdminForth({
     styles:{
       colors: {
         light: {
-          // color for buttons, links, etc.
+          // color for links, focus rings and other accents
           primary: '#16537e',
+          // the action buttons follow the brand color instead of ink
+          buttons: {
+            // background: 'alias:lightPrimary',
+            // border: 'alias:lightPrimary',
+            // hover: 'alias:lightPrimary darken',
+            // borderHover: 'alias:lightPrimary darken',
+            // text: 'alias:lightPrimary inverse',
+          },
           // color for sidebar and text
           sidebar: {
             main:'#232323', 
@@ -126,6 +134,13 @@ export const admin = new AdminForth({
           },
           announcementBG: '#262626',
           announcementText: '#E5E5E5',
+          buttons: {
+            background: 'alias:darkPrimary',
+            border: 'alias:darkPrimary',
+            hover: 'alias:darkPrimary darken',
+            borderHover: 'alias:darkPrimary darken',
+            text: 'alias:darkPrimary inverse',
+          },
         }
       }
     }