[6.x] Improve Storybook Docs

.storybook/manager-head.html

@@ -1,3 +1,8 @@
+<link rel="icon" type="image/x-icon" href="favicon.ico">
+<link rel="icon" type="image/png" sizes="16x16" href="favicon-16x16.png">
+<link rel="icon" type="image/png" sizes="32x32" href="favicon-32x32.png">
+<link rel="apple-touch-icon" sizes="180x180" href="apple-touch-icon.png">
+
 <link rel="preconnect" href="https://fonts.googleapis.com">
 <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
 <link href="https://fonts.googleapis.com/css2?family=Lexend:wght@400;500;600;700&family=Source+Code+Pro:wght@400;500&display=swap" rel="stylesheet">

.storybook/preview-head.html

@@ -1,3 +1,8 @@
+<link rel="icon" type="image/x-icon" href="favicon.ico">
+<link rel="icon" type="image/png" sizes="16x16" href="favicon-16x16.png">
+<link rel="icon" type="image/png" sizes="32x32" href="favicon-32x32.png">
+<link rel="apple-touch-icon" sizes="180x180" href="apple-touch-icon.png">
+
 <link rel="preconnect" href="https://use.typekit.net" crossorigin>
 <link rel="preconnect" href="https://p.typekit.net" crossorigin>
 <link rel="stylesheet" href="https://use.typekit.net/wyy0pka.css"/>

.storybook/preview.ts

@@ -1,25 +1,67 @@
-import type { Preview } from '@storybook/vue3-vite';
-import { setup } from '@storybook/vue3';
-import { create as createTheme } from 'storybook/theming';
-import { router } from '@inertiajs/vue3';
-import { action } from 'storybook/actions';
+import type {Preview} from '@storybook/vue3-vite';
+import {setup} from '@storybook/vue3';
+import {create as createTheme} from 'storybook/theming';
+import {router} from '@inertiajs/vue3';
+import {action} from 'storybook/actions';
 import './storybook.css';
 import './theme.css';
-import { translate } from '@/translations/translator';
+import {translate} from '@/translations/translator';
 import registerUiComponents from '@/bootstrap/ui';
 import DateFormatter from '@/components/DateFormatter';
 import cleanCodeSnippet from './clean-code-snippet';
+import PortalVue from 'portal-vue';
+import FullscreenHeader from '@/components/publish/FullscreenHeader.vue';
+import Portal from '@/components/portals/Portal.vue';
+import PortalTargets from '@/components/portals/PortalTargets.vue';
 
 // Intercept Inertia navigation and log to Actions tab.
 router.on('before', (event) => {
   action('inertia navigate')(event.detail.visit.url);
   return false;
 });
 
+// const portals = markRaw(new Portals());
+// const stacks = new Stacks(portals);
+
 setup(async (app) => {
   window.__ = translate;
+
+  window.Statamic = {
+      $config: {
+          get(key) {
+              const config = {
+                  linkToDocs: true,
+                  paginationSize: 50,
+                  paginationSizeOptions: [10, 25, 50, 100, 500],
+              };
+
+              return config[key] ?? null;
+          }
+      },
+      $commandPalette: {
+          add(command) {
+              //
+          }
+      },
+      $progress: {
+          loading(name, loading) {
+              //
+          }
+      }
+  };
+
   app.config.globalProperties.__ = translate;
   app.config.globalProperties.$date = new DateFormatter;
+  app.config.globalProperties.cp_url = (url) => url;
+  // app.config.globalProperties.$portals = portals;
+  // app.config.globalProperties.$stacks = stacks;
+
+  app.use(PortalVue, { portalName: 'v-portal' });
+
+  app.component('portal', Portal);
+  app.component('PortalTargets', PortalTargets);
+  app.component('publish-field-fullscreen-header', FullscreenHeader);
+
   await registerUiComponents(app);
 });
 
@@ -50,11 +92,11 @@ const preview: Preview = {
         options: {
             storySort: {
                 order: [
-                    // 'Getting Started',
-                    // 'Installation',
-                    '*',
-                    'Components'
+                    'Overview',
+                    'Components',
+                    '*'
                 ],
+                method: 'alphabetical',
             },
         },
     },

.storybook/storybook.css

@@ -1,31 +1,33 @@
 @import 'tailwindcss';
 @import '../resources/css/ui.css';
+@import '../resources/css/core/utilities.css';
+@import '../resources/css/elements/tables.css';
 @custom-variant dark (&:where(.dark, .dark *));
 
-.sbdocs h1,
-.sbdocs h2,
-.sbdocs h3,
-.sbdocs h4,
-.sbdocs h5,
-.sbdocs h6 {
+.sbdocs h1:not(.sbdocs-preview *, .sbdocs-preview h1),
+.sbdocs h2:not(.sbdocs-preview *, .sbdocs-preview h2),
+.sbdocs h3:not(.sbdocs-preview *, .sbdocs-preview h3),
+.sbdocs h4:not(.sbdocs-preview *, .sbdocs-preview h4),
+.sbdocs h5:not(.sbdocs-preview *, .sbdocs-preview h5),
+.sbdocs h6:not(.sbdocs-preview *, .sbdocs-preview h6) {
     font-family: p22-mackinac-pro, serif;
 }
 
-.sbdocs h1 {
+.sbdocs h1:not(.sbdocs-preview *, .sbdocs-preview h1) {
     font-size: 2.5rem;
 }
 
-.sbdocs h2 {
+.sbdocs h2:not(.sbdocs-preview *, .sbdocs-preview h2) {
     font-size: 1.75rem;
     font-weight: 600;
 }
 
-.sbdocs h3 {
+.sbdocs h3:not(.sbdocs-preview *, .sbdocs-preview h3) {
     font-size: 1.25rem;
 }
 
-.sbdocs p,
-.sbdocs li {
+.sbdocs p:not(.sbdocs-preview *, .sbdocs-preview p),
+.sbdocs li:not(.sbdocs-preview *, .sbdocs-preview li) {
     font-size: 1rem;
     line-height: 1.6;
     font-weight: 350;

.storybook/theme.css

@@ -40,3 +40,4 @@ manually copy them here.
         --theme-color-ui-accent-text: oklch(0.673 0.182 276.935);
     }
 }
+

packages/cms/src/ui.js

@@ -17,6 +17,7 @@ export const {
     CommandPaletteItem,
     Context,
     ContextFooter,
+    ContextHeader,
     ContextItem,
     ContextLabel,
     ContextMenu,

resources/js/bootstrap/cms/ui.js

@@ -17,6 +17,7 @@ export {
     CommandPaletteItem,
     Context,
     ContextFooter,
+    ContextHeader,
     ContextItem,
     ContextLabel,
     ContextMenu,

resources/js/components/ui/Avatar.vue

@@ -8,12 +8,16 @@ interface Asset {
 }
 
 interface User {
+    /** Custom initials to display */
     initials?: string;
+    /** Avatar URL or Asset object */
     avatar?: string | Asset;
+    /** User's name (used to generate initials if not provided) */
     name?: string;
 }
 
 interface Props {
+    /** Object with optional properties: `name`, `initials`, `avatar` */
     user: User;
 }
 

resources/js/components/ui/Badge.vue

@@ -6,16 +6,27 @@ import Icon from './Icon/Icon.vue';
 import { Link } from '@inertiajs/vue3';
 
 const props = defineProps({
+    /** Appended text */
     append: { type: [String, Number, Boolean, null], default: null },
+    /** The element or component this component should render as */
     as: { type: String, default: 'div' },
+    /** Controls the color of the badge. <br><br> Options: `default`, `amber`, `black`, `blue`, `cyan`, `emerald`, `fuchsia`, `green`, `indigo`, `lime`, `orange`, `pink`, `purple`, `red`, `rose`, `sky`, `teal`, `violet`, `white`, `yellow` */
     color: { type: String, default: 'default' },
+    /** The URL to link to */
     href: { type: String, default: null },
+    /** When `href` is provided, this prop controls the link's `target` attribute */
     target: { type: String, default: null },
+    /** Icon name. [Browse available icons](/?path=/story/components-icon--all-icons) */
     icon: { type: String, default: null },
+    /** Icon name. Will display after the text. [Browse available icons](/?path=/story/components-icon--all-icons) */
     iconAppend: { type: String, default: null },
+    /** When `true`, the badge will be displayed as a pill */
     pill: { type: Boolean, default: false },
+    /** Prepended text */
     prepend: { type: [String, Number, Boolean, null], default: null },
+    /** Controls the size of the badge. Options: `sm`, `default`, `lg` */
     size: { type: String, default: 'default' },
+    /** Text to display in the badge */
     text: { type: [String, Number, Boolean, null], default: null },
 });
 

resources/js/components/ui/Button/Button.vue

@@ -6,18 +6,31 @@ import Icon from '../Icon/Icon.vue';
 import { Link } from '@inertiajs/vue3';
 
 const props = defineProps({
+    /** The element or component this component should render as */
     as: { type: String, default: null },
+    /** The URL to link to */
     href: { type: String, default: null },
+    /** When `href` is provided, this prop controls the link's `target` attribute */
     target: { type: String, default: null },
+    /** Icon name. [Browse available icons](/?path=/story/components-icon--all-icons) */
     icon: { type: String, default: null },
+    /** Icon name. Will display after the text. [Browse available icons](/?path=/story/components-icon--all-icons) */
     iconAppend: { type: String, default: null },
+    /** When `true`, the button's padding will be adjusted to account for no text */
     iconOnly: { type: Boolean, default: false },
+    /** When using `ghost` or `subtle` button variants, you can use the `inset` prop to remove any invisible padding for better alignment */
     inset: { type: Boolean, default: false },
+    /** When `true`, the button shows an animated loading icon */
     loading: { type: Boolean, default: false },
+    /** When `true`, the button will be rounded */
     round: { type: Boolean, default: false },
+    /** Controls the size of the button. Options: `2xs`, `xs`, `sm`, `base`, `lg` */
     size: { type: String, default: 'base' },
+    /** Text to display in the button */
     text: { type: [String, Number, Boolean, null], default: null },
+    /** Unless `href` is provided, this component defaults to a `<button>`. This prop controls the button's `type` attribute */
     type: { type: String, default: 'button' },
+    /** Controls the appearance of the button. Options: `default`, `primary`, `danger`, `filled`, `ghost`, `ghost-pressed`, `subtle`, `pressed` */
     variant: { type: String, default: 'default' },
 });
 

resources/js/components/ui/Calendar/Calendar.vue

@@ -20,10 +20,15 @@ import Icon from '../Icon/Icon.vue';
 defineOptions({ name: 'Calendar' });
 
 const props = defineProps({
+    /** The controlled value of the calendar. <br><br> Should be an ISO 8601 date and time string with a UTC offset (eg. `2021-11-07T07:45:00Z` or `2021-11-07T07:45:00-07:00`) */
     modelValue: { type: [String, Object], default: null },
+    /** The earliest date that can be selected. Dates before this will be disabled. <br><br> Should be an ISO 8601 date and time string with a UTC offset (eg. `2021-11-07T07:45:00Z` or `2021-11-07T07:45:00-07:00`) */
     min: { type: [String, Object], default: null },
+    /** The latest date that can be selected. Dates after this will be disabled. <br><br> Should be an ISO 8601 date and time string with a UTC offset (eg. `2021-11-07T07:45:00Z` or `2021-11-07T07:45:00-07:00`) */
     max: { type: [String, Object], default: null },
+    /** If necessary, you can you swap out any of the internal Calendar components by passing an object to this prop. */
     components: { type: Object, default: () => ({}) },
+    /** The number of months to display at once. */
     numberOfMonths: { type: Number, default: 1 },
     inline: { type: Boolean, default: false },
 });

resources/js/components/ui/Card/Card.vue

@@ -2,7 +2,9 @@
 import { cva } from 'cva';
 
 const props = defineProps({
+    /** When `true`, the internal padding of the card is removed. */
     inset: { type: Boolean, default: false },
+    /** Controls the appearance of the card. <br><br> Options: `default`, `flat` */
     variant: { type: String, default: 'default' },
 });
 

resources/js/components/ui/CharacterCounter.vue

@@ -2,11 +2,12 @@
 import { computed, ref, watch } from 'vue';
 import { cva } from 'cva';
 
-const emit = defineEmits(['update:text']);
-
 const props = defineProps({
+    /** The text to count characters from */
     text: { type: String, default: '' },
+    /** The maximum number of characters allowed */
     limit: { type: Number, default: null },
+    /** Number of characters remaining before showing the countdown number (default: 20) */
     dangerZone: { type: Number, default: 20 },
 });
 

resources/js/components/ui/Checkbox/Group.vue

@@ -3,8 +3,11 @@ import { useId } from 'vue';
 import { CheckboxGroupRoot } from 'reka-ui';
 
 defineProps({
+    /** When `true`, displays checkboxes horizontally */
     inline: { type: Boolean, default: false },
+    /** The controlled value of the checkbox group */
     modelValue: { type: Array, default: () => [] },
+    /** Name attribute for the checkbox group */
     name: { type: String, default: () => useId() },
     required: { type: Boolean, default: false },
 });

resources/js/components/ui/Checkbox/Item.vue

@@ -4,16 +4,26 @@ import { computed } from 'vue';
 import { cva } from 'cva';
 
 const props = defineProps({
+    /** Controls the vertical alignment of the checkbox with its label. Options: `start`, `center` */
     align: { type: String, default: 'start', validator: (value) => ['start', 'center'].includes(value) },
+    /** Description text to display below the label */
     description: { type: String, default: null },
+    /** When `true`, disables the checkbox */
     disabled: { type: Boolean, default: false },
+    /** Label text to display next to the checkbox */
     label: { type: String, default: null },
+    /** The controlled value of the checkbox */
     modelValue: { type: [Boolean, null], default: null },
+    /** Name attribute for the checkbox input */
     name: { type: String, default: null },
     readOnly: { type: Boolean, default: false },
+    /** Controls the size of the checkbox. Options: `sm`, `base` */
     size: { type: String, default: 'base' },
+    /** When `true`, hides the label and description. Use this when the checkbox is used in a context where the label is provided elsewhere, like in a table cell */
     solo: { type: Boolean, default: false },
+    /** Tab index for keyboard navigation */
     tabindex: { type: Number, default: null },
+    /** Value of the checkbox when used in a group */
     value: { type: [String, Number, Boolean] },
 });
 

resources/js/components/ui/CodeEditor.vue

@@ -39,20 +39,32 @@ import 'codemirror/mode/yaml-frontmatter/yaml-frontmatter';
 const emit = defineEmits(['update:mode', 'update:model-value', 'focus', 'blur']);
 
 const props = defineProps({
+    /** When `true`, displays a mode selector dropdown */
     allowModeSelection: { type: Boolean, default: true },
     disabled: { type: Boolean, default: false },
     fieldActions: { type: Array, default: () => [] },
+    /** Controls whether to indent with tabs or spaces. Options: `tabs`, `spaces` */
     indentType: { type: String, default: 'tabs' },
+    /** Keyboard mapping for the editor. Options: `sublime`, `vim` */
     keyMap: { type: String, default: 'sublime' },
+    /** When `true`, line numbers are displayed */
     lineNumbers: { type: Boolean, default: true },
+    /** When `true`, long lines will wrap */
     lineWrapping: { type: Boolean, default: true },
+    /** The syntax highlighting mode. Options: `clike`, `css`, `diff`, `go`, `haml`, `handlebars`, `htmlmixed`, `less`, `markdown`, `gfm`, `nginx`, `text/x-java`, `javascript`, `jsx`, `text/x-objectivec`, `php`, `python`, `ruby`, `scss`, `shell`, `sql`, `twig`, `vue`, `xml`, `yaml-frontmatter` */
     mode: { type: String, default: 'javascript' },
+    /** The controlled value of the code editor */
     modelValue: { type: String, default: '' },
     readOnly: { type: Boolean, default: false },
+    /** Rulers configuration */
     rulers: { type: Object, default: () => {} },
+    /** When `true`, displays the current mode label */
     showModeLabel: { type: Boolean, default: true },
+    /** The width of a tab character */
     tabSize: { type: Number, required: false },
+    /** Theme of the code editor. Options: `system`, `light`, `dark` */
     colorMode: { type: String, default: 'system' },
+    /** Title displayed in fullscreen mode */
     title: { type: String, default: () => __('Code Editor') },
 });