@imjp/writenex-astro 0.1.0

package/src/client/components/KeyboardShortcuts/KeyboardShortcuts.css

@@ -0,0 +1,239 @@
+/**
+ * @fileoverview KeyboardShortcuts modal styles
+ *
+ * Modal styling for keyboard shortcuts help panel.
+ */
+
+/* ============================================================================
+   MODAL OVERLAY
+   ============================================================================ */
+
+.wn-shortcuts-overlay {
+  position: fixed;
+  inset: 0;
+  z-index: var(--wn-z-modal);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background-color: var(--wn-backdrop);
+  animation: wn-shortcuts-fadeIn var(--wn-transition-fast) ease-out;
+}
+
+@keyframes wn-shortcuts-fadeIn {
+  from {
+    opacity: 0;
+  }
+  to {
+    opacity: 1;
+  }
+}
+
+/* ============================================================================
+   MODAL CONTAINER
+   ============================================================================ */
+
+.wn-shortcuts-modal {
+  width: 100%;
+  max-width: var(--wn-modal-sm);
+  overflow: hidden;
+  border-radius: var(--wn-radius-lg);
+  border: 1px solid var(--wn-zinc-700);
+  background-color: var(--wn-zinc-900);
+  animation: wn-shortcuts-zoomIn var(--wn-transition-fast) ease-out;
+}
+
+.wn-shortcuts-modal--large {
+  max-width: 32rem;
+}
+
+@keyframes wn-shortcuts-zoomIn {
+  from {
+    opacity: 0;
+    transform: scale(0.95);
+  }
+  to {
+    opacity: 1;
+    transform: scale(1);
+  }
+}
+
+/* ============================================================================
+   MODAL HEADER
+   ============================================================================ */
+
+.wn-shortcuts-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: var(--wn-space-4) var(--wn-space-5);
+  border-bottom: 1px solid var(--wn-zinc-700);
+}
+
+.wn-shortcuts-title {
+  font-size: var(--wn-font-base);
+  font-weight: 600;
+  color: var(--wn-zinc-50);
+  margin: 0;
+}
+
+.wn-shortcuts-close {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: var(--wn-icon-btn-md);
+  height: var(--wn-icon-btn-md);
+  padding: 0;
+  border: none;
+  border-radius: var(--wn-radius-md);
+  background-color: transparent;
+  color: var(--wn-zinc-400);
+  cursor: pointer;
+  transition:
+    background-color var(--wn-transition-fast),
+    color var(--wn-transition-fast);
+}
+
+.wn-shortcuts-close:hover {
+  background-color: var(--wn-overlay-10);
+  color: var(--wn-zinc-50);
+}
+
+/* ============================================================================
+   SHORTCUTS LIST
+   ============================================================================ */
+
+.wn-shortcuts-list {
+  max-height: 60vh;
+  overflow-y: auto;
+  padding: var(--wn-space-3);
+}
+
+.wn-shortcuts-section {
+  margin-bottom: var(--wn-space-5);
+}
+
+.wn-shortcuts-section:last-child {
+  margin-bottom: 0;
+}
+
+.wn-shortcuts-category {
+  font-size: var(--wn-font-xs);
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  color: var(--wn-zinc-500);
+  margin: 0 0 var(--wn-space-3) var(--wn-space-4);
+}
+
+.wn-shortcuts-item {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: var(--wn-space-3) var(--wn-space-4);
+  border-radius: var(--wn-radius-md);
+  transition: background-color var(--wn-transition-fast);
+}
+
+.wn-shortcuts-item:hover {
+  background-color: var(--wn-zinc-800);
+}
+
+.wn-shortcuts-item--disabled {
+  opacity: 0.4;
+}
+
+.wn-shortcuts-item--disabled:hover {
+  background-color: transparent;
+}
+
+.wn-shortcuts-label {
+  font-size: var(--wn-font-base);
+  color: var(--wn-zinc-400);
+}
+
+.wn-shortcuts-key {
+  padding: var(--wn-space-1) var(--wn-space-3);
+  border-radius: var(--wn-radius-sm);
+  border: 1px solid var(--wn-zinc-700);
+  background-color: var(--wn-zinc-950);
+  font-family: ui-monospace, monospace;
+  font-size: var(--wn-font-xs);
+  color: var(--wn-zinc-50);
+}
+
+/* ============================================================================
+   MODAL FOOTER
+   ============================================================================ */
+
+.wn-shortcuts-footer {
+  padding: var(--wn-space-4) var(--wn-space-5);
+  border-top: 1px solid var(--wn-zinc-700);
+  text-align: center;
+  font-size: var(--wn-font-xs);
+  color: var(--wn-zinc-600);
+}
+
+.wn-shortcuts-footer kbd {
+  padding: var(--wn-space-1) var(--wn-space-2);
+  border-radius: var(--wn-radius-sm);
+  background-color: var(--wn-zinc-800);
+  color: var(--wn-zinc-400);
+}
+
+/* ============================================================================
+   LIGHT MODE OVERRIDES
+   ============================================================================ */
+
+.wn-light .wn-shortcuts-overlay {
+  background-color: var(--wn-backdrop-light);
+}
+
+.wn-light .wn-shortcuts-modal {
+  border-color: var(--wn-zinc-200);
+  background-color: #fff;
+}
+
+.wn-light .wn-shortcuts-header {
+  border-bottom-color: var(--wn-zinc-200);
+}
+
+.wn-light .wn-shortcuts-title {
+  color: var(--wn-zinc-900);
+}
+
+.wn-light .wn-shortcuts-close {
+  color: var(--wn-zinc-500);
+}
+
+.wn-light .wn-shortcuts-close:hover {
+  background-color: var(--wn-overlay-light-5);
+  color: var(--wn-zinc-900);
+}
+
+.wn-light .wn-shortcuts-category {
+  color: var(--wn-zinc-400);
+}
+
+.wn-light .wn-shortcuts-item:hover {
+  background-color: var(--wn-zinc-100);
+}
+
+.wn-light .wn-shortcuts-label {
+  color: var(--wn-zinc-600);
+}
+
+.wn-light .wn-shortcuts-key {
+  border-color: var(--wn-zinc-200);
+  background-color: var(--wn-zinc-50);
+  color: var(--wn-zinc-900);
+}
+
+.wn-light .wn-shortcuts-footer {
+  border-top-color: var(--wn-zinc-200);
+  color: var(--wn-zinc-400);
+}
+
+.wn-light .wn-shortcuts-footer kbd {
+  background-color: var(--wn-zinc-100);
+  color: var(--wn-zinc-600);
+}

package/src/client/components/KeyboardShortcuts/KeyboardShortcuts.tsx

@@ -0,0 +1,151 @@
+/**
+ * @fileoverview Keyboard shortcuts help modal component
+ *
+ * Displays a modal with all available keyboard shortcuts including
+ * application shortcuts and built-in editor formatting shortcuts.
+ * Includes focus trap for accessibility compliance.
+ *
+ * @module @writenex/astro/client/components/KeyboardShortcuts
+ */
+
+import { useEffect, useRef } from "react";
+import { X } from "lucide-react";
+import { useFocusTrap } from "../../hooks/useFocusTrap";
+import {
+  formatShortcut,
+  type ShortcutDefinition,
+} from "../../hooks/useKeyboardShortcuts";
+import "./KeyboardShortcuts.css";
+
+/**
+ * Built-in editor shortcuts from MDXEditor/Lexical.
+ * These are always available when editing content.
+ */
+const EDITOR_SHORTCUTS: {
+  category: string;
+  shortcuts: { label: string; keys: string }[];
+}[] = [
+  {
+    category: "Formatting",
+    shortcuts: [
+      { label: "Bold", keys: "Ctrl+B" },
+      { label: "Italic", keys: "Ctrl+I" },
+      { label: "Underline", keys: "Ctrl+U" },
+    ],
+  },
+  {
+    category: "Actions",
+    shortcuts: [
+      { label: "Undo", keys: "Ctrl+Z" },
+      { label: "Redo", keys: "Ctrl+Shift+Z" },
+    ],
+  },
+];
+
+/**
+ * Props for ShortcutsHelpModal component
+ */
+interface ShortcutsHelpModalProps {
+  /** List of application shortcuts to display */
+  shortcuts: ShortcutDefinition[];
+  /** Callback to close the modal */
+  onClose: () => void;
+}
+
+/**
+ * Keyboard shortcuts help modal component
+ *
+ * @component
+ * @example
+ * ```tsx
+ * {showHelp && (
+ *   <ShortcutsHelpModal shortcuts={shortcuts} onClose={closeHelp} />
+ * )}
+ * ```
+ */
+export function ShortcutsHelpModal({
+  shortcuts,
+  onClose,
+}: ShortcutsHelpModalProps): React.ReactElement {
+  const triggerRef = useRef<HTMLElement | null>(null);
+
+  // Store the trigger element when modal mounts
+  useEffect(() => {
+    triggerRef.current = document.activeElement as HTMLElement;
+  }, []);
+
+  // Focus trap for accessibility
+  const { containerRef } = useFocusTrap({
+    enabled: true,
+    onEscape: onClose,
+    returnFocusTo: triggerRef.current,
+  });
+
+  const handleOverlayClick = (e: React.MouseEvent) => {
+    if (e.target === e.currentTarget) onClose();
+  };
+
+  return (
+    <div className="wn-shortcuts-overlay" onClick={handleOverlayClick}>
+      <div
+        ref={containerRef}
+        className="wn-shortcuts-modal wn-shortcuts-modal--large"
+        role="dialog"
+        aria-modal="true"
+        aria-labelledby="shortcuts-title"
+      >
+        {/* Header */}
+        <div className="wn-shortcuts-header">
+          <h2 id="shortcuts-title" className="wn-shortcuts-title">
+            Keyboard Shortcuts
+          </h2>
+          <button
+            className="wn-shortcuts-close"
+            onClick={onClose}
+            title="Close (Esc)"
+            aria-label="Close shortcuts help"
+          >
+            <X size={16} />
+          </button>
+        </div>
+
+        {/* Shortcuts List */}
+        <div className="wn-shortcuts-list">
+          {/* Application Shortcuts */}
+          <div className="wn-shortcuts-section">
+            <h3 className="wn-shortcuts-category">Application</h3>
+            {shortcuts.map((shortcut) => (
+              <div
+                key={shortcut.key}
+                className={`wn-shortcuts-item ${shortcut.enabled === false ? "wn-shortcuts-item--disabled" : ""}`}
+              >
+                <span className="wn-shortcuts-label">{shortcut.label}</span>
+                <kbd className="wn-shortcuts-key">
+                  {formatShortcut(shortcut)}
+                </kbd>
+              </div>
+            ))}
+          </div>
+
+          {/* Editor Shortcuts */}
+          {EDITOR_SHORTCUTS.map((group) => (
+            <div key={group.category} className="wn-shortcuts-section">
+              <h3 className="wn-shortcuts-category">{group.category}</h3>
+              {group.shortcuts.map((shortcut) => (
+                <div key={shortcut.label} className="wn-shortcuts-item">
+                  <span className="wn-shortcuts-label">{shortcut.label}</span>
+                  <kbd className="wn-shortcuts-key">{shortcut.keys}</kbd>
+                </div>
+              ))}
+            </div>
+          ))}
+        </div>
+
+        {/* Footer */}
+        <div className="wn-shortcuts-footer">
+          Press <kbd>Ctrl+/</kbd> to toggle this help
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/client/components/KeyboardShortcuts/index.ts

@@ -0,0 +1,6 @@
+/**
+ * @fileoverview KeyboardShortcuts component exports
+ * @module @writenex/astro/client/components/KeyboardShortcuts
+ */
+
+export { ShortcutsHelpModal } from "./KeyboardShortcuts";

package/src/client/components/LazyEditor.tsx

@@ -0,0 +1,75 @@
+/**
+ * @fileoverview Lazy-loaded Editor component
+ *
+ * This module provides a lazy-loaded version of the MDXEditor component
+ * to improve initial bundle size and load time. The actual editor is
+ * loaded on-demand when the component mounts.
+ *
+ * @module @writenex/astro/client/components/LazyEditor
+ */
+
+import { lazy, Suspense, memo } from "react";
+import { EditorLoading } from "./Editor/Editor";
+
+/**
+ * Props for LazyEditor - same as Editor
+ */
+interface LazyEditorProps {
+  /** Initial markdown content */
+  initialContent: string;
+  /** Callback when content changes */
+  onChange: (markdown: string) => void;
+  /** Whether the editor is read-only */
+  readOnly?: boolean;
+  /** Placeholder text when empty */
+  placeholder?: string;
+  /** Handler for image uploads. Returns the image URL/path on success. */
+  onImageUpload?: (file: File) => Promise<string | null>;
+  /** Base path for API requests */
+  basePath?: string;
+  /** Current collection name (for image URL resolution) */
+  collection?: string;
+  /** Current content ID (for image URL resolution) */
+  contentId?: string;
+  /** Search query for highlighting */
+  searchQuery?: string;
+  /** Current search match index (1-based) */
+  searchActiveIndex?: number;
+}
+
+/**
+ * Lazy-loaded Editor component
+ *
+ * Uses React.lazy to defer loading the MDXEditor bundle until needed.
+ */
+const LazyEditorComponent = lazy(() =>
+  import("./Editor/Editor").then((mod) => ({ default: mod.Editor }))
+);
+
+/**
+ * Editor wrapper with Suspense fallback
+ *
+ * This component wraps the lazy-loaded Editor with a Suspense boundary
+ * that shows a loading indicator while the editor bundle loads.
+ *
+ * @example
+ * ```tsx
+ * <LazyEditor
+ *   initialContent={markdown}
+ *   onChange={handleChange}
+ *   placeholder="Start writing..."
+ * />
+ * ```
+ */
+export const LazyEditor = memo(function LazyEditor(
+  props: LazyEditorProps
+): React.ReactElement {
+  return (
+    <Suspense fallback={<EditorLoading />}>
+      <LazyEditorComponent {...props} />
+    </Suspense>
+  );
+});
+
+// Re-export EditorEmpty and EditorLoading for convenience
+export { EditorEmpty, EditorLoading } from "./Editor/Editor";

package/src/client/components/LiveRegion/LiveRegion.css

@@ -0,0 +1,19 @@
+/**
+ * @fileoverview Live Region component styles
+ *
+ * Styles for the live region component that is visually hidden
+ * but accessible to screen readers.
+ */
+
+/* Live region - visually hidden but accessible */
+.wn-live-region {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}

package/src/client/components/LiveRegion/LiveRegion.tsx

@@ -0,0 +1,60 @@
+/**
+ * @fileoverview Live Region component for screen reader announcements
+ *
+ * A global live region component that announces dynamic content changes
+ * to screen readers. Integrates with the useAnnounce hook to provide
+ * a centralized announcement system.
+ *
+ * @module @writenex/astro/client/components/LiveRegion
+ * @see {@link useAnnounce} - Hook for triggering announcements
+ */
+
+import type { AnnouncePoliteness } from "../../hooks/useAnnounce";
+import "./LiveRegion.css";
+
+/**
+ * Props for the LiveRegion component
+ */
+export interface LiveRegionProps {
+  /** Current message to announce */
+  message: string;
+  /** Politeness level - polite waits, assertive interrupts */
+  politeness?: AnnouncePoliteness;
+}
+
+/**
+ * Live region component for screen reader announcements
+ *
+ * Renders an ARIA live region that announces messages to screen readers.
+ * The component is visually hidden but accessible to assistive technology.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * function App() {
+ *   const { currentMessage, currentPoliteness } = useAnnounce();
+ *
+ *   return (
+ *     <>
+ *       <LiveRegion message={currentMessage} politeness={currentPoliteness} />
+ *       {/* rest of app *\/}
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+export function LiveRegion({
+  message,
+  politeness = "polite",
+}: LiveRegionProps): React.ReactElement {
+  return (
+    <div
+      role="status"
+      aria-live={politeness}
+      aria-atomic="true"
+      className="wn-live-region"
+    >
+      {message}
+    </div>
+  );
+}

package/src/client/components/LiveRegion/index.ts

@@ -0,0 +1,7 @@
+/**
+ * @fileoverview LiveRegion component exports
+ * @module @writenex/astro/client/components/LiveRegion
+ */
+
+export { LiveRegion } from "./LiveRegion";
+export type { LiveRegionProps } from "./LiveRegion";