@umami/shiso 1.15.0 → 1.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umami/shiso",
-  "version": "1.15.0",
+  "version": "1.17.0",
   "description": "Open-source documentation framework for Markdown and MDX sites.",
   "type": "module",
   "bin": {

package/scripts/lib/openapi.mjs

@@ -372,7 +372,12 @@ export function normalizeOperations(spec) {
       const serverUrl = operation.servers?.[0]?.url || spec.servers?.[0]?.url || FALLBACK_SERVER;
       const normalized = {
         id: slugify(
-          operation.operationId || `${method}-${pathName}`,
+          operation.operationId
+            ? operation.operationId
+                .replace(/([A-Z]+)([A-Z][a-z])/g, '$1-$2')
+                .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+                .replace(/[_\s]+/g, '-')
+            : `${method}-${pathName}`,
           `${method}-${slugify(pathName, 'root')}`,
         ),
         key: `${upper} ${pathName}`,

package/src/App.tsx

@@ -12,8 +12,16 @@ import { docsHomeUrl, hasRootStandalonePage, siteModel, standalonePages } from '
 import { DocPage } from '@/pages/DocPage';
 import { StandalonePageView } from '@/pages/StandalonePage';
 
+// Runtime helpers are public exports, but cannot be rendered as MDX components.
+const {
+  mermaidSource: _mermaidSource,
+  usePanelContent: _usePanelContent,
+  useSetPanelContent: _useSetPanelContent,
+  ...mdxDocsComponents
+} = docsComponents;
+
 const mdxComponents = {
-  ...docsComponents,
+  ...mdxDocsComponents,
   img: docsComponents.ZoomableImage,
   pre: CodeBlock,
 };

package/src/components/DocContent.tsx

@@ -3,6 +3,7 @@ import { ContextualMenu } from '@/components/ContextualMenu';
 import { Badge } from '@/components/docs/Badge';
 import { ArrowLeft, ArrowRight, FileText } from '@/components/icons';
 import { OpenApiOperation } from '@/components/OpenApiOperation';
+import { PageActions } from '@/components/PageActions';
 import { getLastModified } from '@/lib/content';
 import { getScopeForPage } from '@/lib/docs-config';
 import { resolveLocale } from '@/lib/locale';
@@ -135,12 +136,20 @@ export function DocContent({ page, doc, site }: DocContentProps) {
         <Content />
       </div>
       {operation && <OpenApiOperation operation={operation} />}
-      {lastModified && (
-        <div className="mt-8 text-sm text-muted-foreground">
-          {site.labels.lastUpdated}{' '}
-          <time dateTime={lastModified}>{dateFormat.format(new Date(lastModified))}</time>
-        </div>
-      )}
+      <PageActions
+        key={page.url}
+        page={page}
+        frontmatter={doc.frontmatter}
+        site={site}
+        lastUpdated={
+          lastModified ? (
+            <>
+              {site.labels.lastUpdated}{' '}
+              <time dateTime={lastModified}>{dateFormat.format(new Date(lastModified))}</time>
+            </>
+          ) : undefined
+        }
+      />
       {related.length > 0 && (
         <nav className="mt-8" aria-label={site.labels.relatedTopics} data-pagefind-ignore>
           <div className="text-sm text-muted-foreground">{site.labels.relatedTopics}</div>

package/src/components/LanguageSwitcher.tsx

@@ -8,13 +8,15 @@ import {
   DropdownMenuTrigger,
 } from '@/components/ui/dropdown-menu';
 import { getLanguageScopes } from '@/lib/docs-config';
+import { getLanguageName, isValidLocale } from '@/lib/locale';
 import { docsSite, getScopeByPathname } from '@/lib/site-config';
 
 /**
  * Language selector for multi-language sites. Each option is a language's
  * landing scope — its default version — so switching languages always lands
  * on that language's default-version first page. Hidden languages never
- * appear as options.
+ * appear as options. Each language is shown by its native name, e.g. "ja"
+ * as "日本語".
  */
 export function LanguageSwitcher() {
   const { pathname } = useLocation();
@@ -36,7 +38,7 @@ export function LanguageSwitcher() {
           />
         }
       >
-        {current.language}
+        {getLanguageName(current.language)}
         <ChevronRight className="size-3.5 rotate-90 text-muted-foreground" />
       </DropdownMenuTrigger>
       <DropdownMenuContent align="start" className="min-w-32">
@@ -49,7 +51,12 @@ export function LanguageSwitcher() {
               }
             }}
           >
-            <span className="grow">{scope.language}</span>
+            <span
+              className="grow"
+              lang={isValidLocale(scope.language) ? scope.language : undefined}
+            >
+              {scope.language ? getLanguageName(scope.language) : null}
+            </span>
             {scope.language === current.language ? <Check className="size-3.5" /> : null}
           </DropdownMenuItem>
         ))}

package/src/components/PageActions.tsx

@@ -0,0 +1,134 @@
+import { type ReactNode, useEffect, useRef, useState } from 'react';
+import { ExternalLink } from '@/components/icons';
+import { toHref } from '@/lib/paths';
+import type { DocFrontmatter, NormalizedDocsPage, SiteModel } from '@/lib/types';
+
+function editHref(template: string | undefined, filePath: string): string | undefined {
+  if (!template) return undefined;
+  const file = filePath.replace(/^\/+/, '').split('/').map(encodeURIComponent).join('/');
+  const href = template.replaceAll('$file', file);
+  try {
+    const url = new URL(href);
+    if (url.protocol === 'https:' || url.protocol === 'http:') return url.href;
+  } catch {
+    // Invalid frontmatter URLs should never become executable links.
+  }
+  return undefined;
+}
+
+export function PageActions({
+  page,
+  frontmatter,
+  site,
+  lastUpdated,
+}: {
+  page: NormalizedDocsPage;
+  frontmatter?: DocFrontmatter;
+  site: SiteModel;
+  lastUpdated?: ReactNode;
+}) {
+  const [status, setStatus] = useState<'idle' | 'pending' | 'success' | 'error'>('idle');
+  const [rating, setRating] = useState<boolean>();
+  const request = useRef<AbortController | null>(null);
+  useEffect(() => () => request.current?.abort(), []);
+
+  const feedback = frontmatter?.feedback === false ? null : site.feedback;
+  const href =
+    frontmatter?.editLink === false
+      ? undefined
+      : editHref(
+          typeof frontmatter?.editLink === 'string' ? frontmatter.editLink : site.editLink?.url,
+          page.filePath,
+        );
+
+  async function submit(helpful: boolean) {
+    if (!feedback || request.current || status === 'success') return;
+    const controller = new AbortController();
+    request.current = controller;
+    setRating(helpful);
+    setStatus('pending');
+    const timeout = window.setTimeout(() => controller.abort(), 15000);
+    try {
+      const endpoint = new URL(toHref(feedback.endpoint), window.location.origin);
+      if (!['https:', 'http:'].includes(endpoint.protocol)) throw new Error('Invalid endpoint');
+      const response = await fetch(endpoint.href, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          helpful,
+          path: toHref(page.url),
+          title: frontmatter?.title || page.label,
+          language: page.language,
+          version: page.version,
+        }),
+        signal: controller.signal,
+      });
+      if (!response.ok) throw new Error('Feedback submission failed');
+      setStatus('success');
+    } catch {
+      setStatus('error');
+    } finally {
+      window.clearTimeout(timeout);
+      request.current = null;
+    }
+  }
+
+  if (!href && !feedback && !lastUpdated) return null;
+
+  return (
+    <>
+      {(lastUpdated || href) && (
+        <div
+          className="mt-8 flex items-baseline gap-4 text-sm text-muted-foreground"
+          data-pagefind-ignore
+        >
+          {lastUpdated && <div className="min-w-0">{lastUpdated}</div>}
+          {href && (
+            <a
+              href={href}
+              target="_blank"
+              rel="noopener noreferrer"
+              className="ml-auto inline-flex shrink-0 items-center gap-1.5 text-right no-underline hover:text-primary"
+            >
+              {site.editLink?.label || 'Edit this page'}
+              <ExternalLink size={14} aria-hidden="true" />
+            </a>
+          )}
+        </div>
+      )}
+      {feedback && (
+        <div
+          className="mt-8 flex flex-col gap-2 border-t border-border pt-6 text-sm"
+          aria-busy={status === 'pending'}
+          data-pagefind-ignore
+        >
+          <fieldset
+            aria-label={feedback.prompt || 'Was this page helpful?'}
+            className="flex flex-wrap items-center gap-2"
+          >
+            <span className="mr-2 text-muted-foreground">
+              {feedback.prompt || 'Was this page helpful?'}
+            </span>
+            {[true, false].map(helpful => (
+              <button
+                key={String(helpful)}
+                type="button"
+                aria-pressed={rating === helpful}
+                disabled={status === 'pending' || status === 'success'}
+                onClick={() => void submit(helpful)}
+                className="rounded-md border border-border px-3 py-1.5 text-foreground hover:bg-muted focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary disabled:cursor-default disabled:opacity-60 aria-pressed:border-primary aria-pressed:text-primary"
+              >
+                {helpful ? feedback.helpfulLabel || 'Yes' : feedback.unhelpfulLabel || 'No'}
+              </button>
+            ))}
+          </fieldset>
+          <div role="status" aria-live="polite" className="text-muted-foreground">
+            {status === 'success' && (feedback.successMessage || 'Thanks for your feedback!')}
+            {status === 'error' &&
+              (feedback.errorMessage || 'Could not send feedback. Please try again.')}
+          </div>
+        </div>
+      )}
+    </>
+  );
+}

package/src/components/docs/Changelog.tsx

@@ -1,4 +1,11 @@
-import { Children, Fragment, isValidElement, type ReactElement, useMemo } from 'react';
+import {
+  Children,
+  Fragment,
+  isValidElement,
+  type ReactElement,
+  type ReactNode,
+  useMemo,
+} from 'react';
 import { useSearchParams } from 'react-router';
 import { Badge } from './Badge';
 import { styles } from './styles';
@@ -13,12 +20,17 @@ interface UpdateChildInfo {
   tags: string[];
 }
 
+interface UpdateChildProps {
+  tags?: unknown;
+  children?: ReactNode;
+}
+
 /** Flattens fragments so <Update> entries are found however MDX nests them. */
-function flatElements(children: React.ReactNode): ReactElement<{ tags?: unknown }>[] {
-  const flat: ReactElement<{ tags?: unknown }>[] = [];
+function flatElements(children: React.ReactNode): ReactElement<UpdateChildProps>[] {
+  const flat: ReactElement<UpdateChildProps>[] = [];
 
   Children.forEach(children, child => {
-    if (!isValidElement<{ tags?: unknown }>(child)) {
+    if (!isValidElement<UpdateChildProps>(child)) {
       return;
     }
     if (child.type === Fragment) {
@@ -43,9 +55,11 @@ function updateInfo(children: React.ReactNode): Map<string, UpdateChildInfo> {
     const key = String(child.key ?? `update-${index}`);
     const raw = child.props.tags;
     const tags = Array.isArray(raw)
-      ? [...new Set(raw.filter((tag): tag is string => typeof tag === 'string' && tag.trim()))].map(
-          tag => tag.trim(),
-        )
+      ? [
+          ...new Set(
+            raw.filter((tag): tag is string => typeof tag === 'string' && tag.trim().length > 0),
+          ),
+        ].map(tag => tag.trim())
       : [];
     info.set(key, { key, tags });
   });
@@ -142,7 +156,7 @@ export function Changelog({ children }: ChangelogProps) {
               className={styles.changelogFilterButton}
               data-active={active ? '' : undefined}
             >
-              <Badge size="sm" color={active ? 'primary' : undefined}>
+              <Badge size="sm" tone={active ? 'primary' : undefined}>
                 {tag}
               </Badge>
             </button>

package/src/lib/locale.ts

@@ -37,3 +37,28 @@ export function getTextDirection(locale: string): 'ltr' | 'rtl' {
   const primary = locale.split('-')[0]?.toLowerCase() || '';
   return RTL_LANGUAGES.has(primary) ? 'rtl' : 'ltr';
 }
+
+/**
+ * A language's name written in that language, for language selectors:
+ * "ja" -> "日本語", "zh-Hant" -> "繁體中文", "es" -> "Español". Labels that
+ * are not valid locale codes (e.g. "English") are returned unchanged.
+ */
+export function getLanguageName(language: string): string {
+  if (!isValidLocale(language)) {
+    return language;
+  }
+
+  const locale = Intl.getCanonicalLocales(language)[0];
+
+  try {
+    const name = new Intl.DisplayNames([locale], { type: 'language', fallback: 'none' }).of(locale);
+
+    if (!name) {
+      return language;
+    }
+
+    return name.charAt(0).toLocaleUpperCase(locale) + name.slice(1);
+  } catch {
+    return language;
+  }
+}

package/src/lib/site-model.ts

@@ -136,6 +136,8 @@ export function resolveSiteModel(
     search: resolveSearchConfig(config.search),
     contextualOptions: config.contextual?.options || [],
     error404: { ...config.errors?.['404'], redirect: config.errors?.['404']?.redirect !== false },
+    editLink: config.editLink || null,
+    feedback: config.feedback || null,
     showTimestamp: config.metadata?.timestamp === true,
     drilldown: config.interaction?.drilldown,
     locale: shiso?.locale || 'en-US',

package/src/lib/types.ts

@@ -242,6 +242,22 @@ export interface ErrorsConfig {
   '404'?: Error404Config;
 }
 
+export interface EditLinkConfig {
+  /** HTTP(S) URL template. $file is the encoded source path relative to the project root. */
+  url: string;
+  label?: string;
+}
+
+export interface FeedbackConfig {
+  /** HTTP(S) or site-relative endpoint accepting a JSON POST. */
+  endpoint: string;
+  prompt?: string;
+  helpfulLabel?: string;
+  unhelpfulLabel?: string;
+  successMessage?: string;
+  errorMessage?: string;
+}
+
 export interface MetadataConfig {
   /** Show the last-modified date on all pages. Overridable per page via `timestamp` frontmatter. */
   timestamp?: boolean;
@@ -372,6 +388,8 @@ export interface DocsConfig {
   seo?: SeoConfig;
   errors?: ErrorsConfig;
   metadata?: MetadataConfig;
+  editLink?: false | EditLinkConfig;
+  feedback?: false | FeedbackConfig;
   appearance?: AppearanceConfig;
   styling?: StylingConfig;
   fonts?: FontsConfig;
@@ -584,6 +602,8 @@ export interface SiteModel {
   contextualOptions: ContextualOption[];
   error404: Required<Pick<Error404Config, 'redirect'>> & Error404Config;
   showTimestamp: boolean;
+  editLink?: EditLinkConfig | null;
+  feedback?: FeedbackConfig | null;
   drilldown?: boolean;
   locale: string;
   labels: ThemeLabels;
@@ -614,6 +634,10 @@ export interface TocEntry {
 export type RelatedEntry = string | { href: string; title?: string };
 
 export interface DocFrontmatter {
+  /** Override the edit URL, or hide the edit link on this page. */
+  editLink?: string | false;
+  /** Hide the feedback controls on this page. */
+  feedback?: false;
   title?: string;
   description?: string;
   noindex?: boolean;

package/src/styles/global.css

@@ -183,7 +183,7 @@
     border-radius: var(--radius-sm);
     background: color-mix(in srgb, currentColor 4%, transparent);
     padding: 0.1rem 0.3rem;
-    font-size: 0.875rem;
+    font-size: 0.875em;
   }
 
   /* Shared by GFM tables and the PropertiesTable component: rounded outer border,