@orhancodestudio/ocsm-core 0.1.0-alpha.1

package/src/blocks/block.types.ts

@@ -0,0 +1,401 @@
+/** The kinds of section blocks a page can contain. */
+export type BlockType =
+  | "navbar"
+  | "hero"
+  | "heading"
+  | "richText"
+  | "image"
+  | "button"
+  | "quote"
+  | "banner"
+  | "marquee"
+  | "video"
+  | "spacer";
+
+export type TextAlign = "left" | "center" | "right";
+
+export type BackgroundType = "solid" | "gradient";
+
+/** Shared visual style applied to a section. Empty string = inherit/default. */
+export interface BlockStyle {
+  bgType: BackgroundType;
+  background: string;
+  gradientFrom: string;
+  gradientTo: string;
+  gradientAngle: string;
+  textColor: string;
+  textAlign: TextAlign;
+  fontFamily: string;
+  fontSize: string;
+  fontWeight: string;
+  paddingY: string;
+  maxWidth: string;
+}
+
+interface WithStyle {
+  id: string;
+  style: BlockStyle;
+  /** When true, the block is hidden on the public site. */
+  hidden?: boolean;
+}
+
+export interface NavLink {
+  label: string;
+  url: string;
+}
+
+export interface NavbarBlock extends WithStyle {
+  type: "navbar";
+  logoText: string;
+  logoImageUrl: string;
+  logoHref: string;
+  logoAlign: TextAlign;
+  links: NavLink[];
+  linksAlign: TextAlign;
+  /** When true, the header sticks to the top while scrolling (CSS `position: sticky`). */
+  sticky: boolean;
+}
+
+export interface HeroBlock extends WithStyle {
+  type: "hero";
+  heading: string;
+  subheading: string;
+  buttonLabel: string;
+  buttonUrl: string;
+  buttonColor: string;
+}
+
+export interface HeadingBlock extends WithStyle {
+  type: "heading";
+  text: string;
+  level: 1 | 2 | 3;
+}
+
+export interface RichTextBlock extends WithStyle {
+  type: "richText";
+  markdown: string;
+}
+
+export interface ImageBlock extends WithStyle {
+  type: "image";
+  url: string;
+  alt: string;
+  caption: string;
+  width: string;
+  height: string;
+  radius: string;
+  fit: "cover" | "contain" | "fill";
+  link: string;
+}
+
+export interface ButtonBlock extends WithStyle {
+  type: "button";
+  label: string;
+  url: string;
+  buttonColor: string;
+}
+
+export interface QuoteBlock extends WithStyle {
+  type: "quote";
+  text: string;
+  author: string;
+}
+
+export interface BannerBlock extends WithStyle {
+  type: "banner";
+  text: string;
+  url: string;
+}
+
+export interface MarqueeBlock extends WithStyle {
+  type: "marquee";
+  text: string;
+  speed: string;
+  direction: "left" | "right";
+  repeat: string;
+  gap: string;
+}
+
+export interface VideoBlock extends WithStyle {
+  type: "video";
+  url: string;
+}
+
+export interface SpacerBlock extends WithStyle {
+  type: "spacer";
+  height: string;
+}
+
+export type Block =
+  | NavbarBlock
+  | HeroBlock
+  | HeadingBlock
+  | RichTextBlock
+  | ImageBlock
+  | ButtonBlock
+  | QuoteBlock
+  | BannerBlock
+  | MarqueeBlock
+  | VideoBlock
+  | SpacerBlock;
+
+/** Block types in the order they appear in the "add section" menu. */
+export const BLOCK_TYPES: ReadonlyArray<{
+  type: BlockType;
+  label: string;
+  icon: string;
+  /** Only offered in the global header region. */
+  headerOnly?: boolean;
+}> = [
+  { type: "navbar", label: "Üst Bilgi", icon: "▤", headerOnly: true },
+  { type: "hero", label: "Hero", icon: "★" },
+  { type: "heading", label: "Başlık", icon: "H" },
+  { type: "richText", label: "Metin", icon: "¶" },
+  { type: "image", label: "Görsel", icon: "▣" },
+  { type: "button", label: "Buton", icon: "◉" },
+  { type: "quote", label: "Alıntı", icon: "❝" },
+  { type: "banner", label: "Banner", icon: "▭" },
+  { type: "marquee", label: "Kayan Yazı", icon: "↔" },
+  { type: "video", label: "Video", icon: "▶" },
+  { type: "spacer", label: "Boşluk", icon: "↕" },
+];
+
+export const FONT_OPTIONS: ReadonlyArray<{ label: string; value: string }> = [
+  { label: "Tema (varsayılan)", value: "" },
+  { label: "Sistem", value: "system-ui, -apple-system, sans-serif" },
+  { label: "Inter / Sans", value: "Inter, system-ui, sans-serif" },
+  { label: "Georgia (serif)", value: "Georgia, 'Times New Roman', serif" },
+  { label: "Times (serif)", value: "'Times New Roman', Times, serif" },
+  { label: "Arial", value: "Arial, Helvetica, sans-serif" },
+  { label: "Courier (mono)", value: "'Courier New', ui-monospace, monospace" },
+];
+
+export const FONT_WEIGHT_OPTIONS: ReadonlyArray<{ label: string; value: string }> =
+  [
+    { label: "Varsayılan", value: "" },
+    { label: "İnce (300)", value: "300" },
+    { label: "Normal (400)", value: "400" },
+    { label: "Orta (500)", value: "500" },
+    { label: "Yarı kalın (600)", value: "600" },
+    { label: "Kalın (700)", value: "700" },
+    { label: "Çok kalın (800)", value: "800" },
+  ];
+
+/** Curated gradient presets offered in the inspector. */
+export const GRADIENT_PRESETS: ReadonlyArray<{
+  label: string;
+  from: string;
+  to: string;
+  angle: string;
+}> = [
+  { label: "Gün batımı", from: "#ff6a00", to: "#ee0979", angle: "135" },
+  { label: "Okyanus", from: "#2193b0", to: "#6dd5ed", angle: "135" },
+  { label: "Mor sis", from: "#7c3aed", to: "#2563eb", angle: "135" },
+  { label: "Orman", from: "#11998e", to: "#38ef7d", angle: "135" },
+  { label: "Gece", from: "#0f2027", to: "#2c5364", angle: "160" },
+  { label: "Şeftali", from: "#ffecd2", to: "#fcb69f", angle: "120" },
+];
+
+const BLOCK_TYPE_SET = new Set<BlockType>([
+  "navbar",
+  "hero",
+  "heading",
+  "richText",
+  "image",
+  "button",
+  "quote",
+  "banner",
+  "marquee",
+  "video",
+  "spacer",
+]);
+
+export function isBlockType(value: string): value is BlockType {
+  return BLOCK_TYPE_SET.has(value as BlockType);
+}
+
+function baseStyle(overrides: Partial<BlockStyle> = {}): BlockStyle {
+  return {
+    bgType: "solid",
+    background: "",
+    gradientFrom: "#7c3aed",
+    gradientTo: "#2563eb",
+    gradientAngle: "135",
+    textColor: "",
+    textAlign: "left",
+    fontFamily: "",
+    fontSize: "",
+    fontWeight: "",
+    paddingY: "32",
+    maxWidth: "720",
+    ...overrides,
+  };
+}
+
+/** Creates a new block of the given type with sensible defaults and a fresh id. */
+export function createBlock(type: BlockType): Block {
+  const id = newId();
+  switch (type) {
+    case "navbar":
+      return {
+        id,
+        type,
+        logoText: "ACME",
+        logoImageUrl: "",
+        logoHref: "/",
+        logoAlign: "left",
+        links: [
+          { label: "Anasayfa", url: "/" },
+          { label: "Hizmetler", url: "/p/hizmetler" },
+          { label: "İletişim", url: "/p/iletisim" },
+        ],
+        linksAlign: "right",
+        sticky: false,
+        style: baseStyle({
+          background: "#ffffff",
+          textColor: "#0f172a",
+          paddingY: "16",
+          maxWidth: "1080",
+        }),
+      };
+    case "hero":
+      return {
+        id,
+        type,
+        heading: "Etkileyici bir başlık",
+        subheading: "Kısa bir açıklama metni buraya gelir.",
+        buttonLabel: "Başla",
+        buttonUrl: "#",
+        buttonColor: "#2563eb",
+        style: baseStyle({
+          background: "#0f172a",
+          textColor: "#ffffff",
+          textAlign: "center",
+          paddingY: "88",
+        }),
+      };
+    case "heading":
+      return {
+        id,
+        type,
+        text: "Bölüm başlığı",
+        level: 2,
+        style: baseStyle({ paddingY: "10", fontWeight: "700" }),
+      };
+    case "richText":
+      return {
+        id,
+        type,
+        markdown: "Buraya **zengin** metin yazın.",
+        style: baseStyle({ paddingY: "16" }),
+      };
+    case "image":
+      return {
+        id,
+        type,
+        url: "",
+        alt: "",
+        caption: "",
+        width: "100",
+        height: "",
+        radius: "12",
+        fit: "cover",
+        link: "",
+        style: baseStyle({ textAlign: "center", paddingY: "16" }),
+      };
+    case "button":
+      return {
+        id,
+        type,
+        label: "Tıkla",
+        url: "#",
+        buttonColor: "#2563eb",
+        style: baseStyle({ textAlign: "center", paddingY: "16" }),
+      };
+    case "quote":
+      return {
+        id,
+        type,
+        text: "İlham veren bir alıntı buraya gelir.",
+        author: "Yazar",
+        style: baseStyle({ paddingY: "24" }),
+      };
+    case "banner":
+      return {
+        id,
+        type,
+        text: "Duyuru: yeni bir şeyler var!",
+        url: "",
+        style: baseStyle({
+          background: "#2563eb",
+          textColor: "#ffffff",
+          textAlign: "center",
+          paddingY: "14",
+          maxWidth: "full",
+        }),
+      };
+    case "marquee":
+      return {
+        id,
+        type,
+        text: "Kayan duyuru metni",
+        speed: "16",
+        direction: "left",
+        repeat: "4",
+        gap: "60",
+        style: baseStyle({
+          background: "#0f172a",
+          textColor: "#ffffff",
+          paddingY: "12",
+          maxWidth: "full",
+        }),
+      };
+    case "video":
+      return {
+        id,
+        type,
+        url: "",
+        style: baseStyle({ paddingY: "24", maxWidth: "820" }),
+      };
+    case "spacer":
+      return {
+        id,
+        type,
+        height: "48",
+        style: baseStyle({ paddingY: "0" }),
+      };
+  }
+}
+
+/** Leniently parses untrusted data (e.g. frontmatter) into a typed block list. */
+export function normalizeBlocks(value: unknown): Block[] {
+  if (!Array.isArray(value)) return [];
+  const blocks: Block[] = [];
+  for (const raw of value) {
+    if (!raw || typeof raw !== "object") continue;
+    const record = raw as Record<string, unknown>;
+    const type = record.type;
+    if (typeof type !== "string" || !isBlockType(type)) continue;
+    const base = createBlock(type);
+    const style = isObject(record.style)
+      ? { ...base.style, ...(record.style as Partial<BlockStyle>) }
+      : base.style;
+    blocks.push({
+      ...base,
+      ...record,
+      type,
+      id: typeof record.id === "string" ? record.id : base.id,
+      style,
+    } as Block);
+  }
+  return blocks;
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function newId(): string {
+  const uuid = globalThis.crypto?.randomUUID?.();
+  return uuid ?? `b-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+}

package/src/blocks/index.ts

@@ -0,0 +1,15 @@
+export {
+  type BannerBlock,
+  type Block,
+  type BlockType,
+  BLOCK_TYPES,
+  createBlock,
+  type HeadingBlock,
+  type HeroBlock,
+  type ImageBlock,
+  isBlockType,
+  normalizeBlocks,
+  type RichTextBlock,
+} from "./block.types";
+export { BlockRenderer } from "./block-renderer";
+export { OcsmMarkdown } from "./markdown";

package/src/blocks/markdown.tsx

@@ -0,0 +1,11 @@
+import Markdown from "react-markdown";
+import remarkGfm from "remark-gfm";
+
+/**
+ * Renders a Markdown string. Isomorphic — safe in both Server and Client
+ * Components. Replaces MDX rendering (which is incompatible with the current
+ * React/Next versions).
+ */
+export function OcsmMarkdown({ children }: { children: string }) {
+  return <Markdown remarkPlugins={[remarkGfm]}>{children}</Markdown>;
+}

package/src/config/config.schema.ts

@@ -0,0 +1,28 @@
+import { z } from "zod";
+
+/** Branding shown in the admin panel and (optionally) the public site. */
+export const ocsmBrandSchema = z.object({
+  name: z.string().min(1),
+  description: z.string().optional(),
+  logoUrl: z.string().url().optional(),
+});
+
+/** A single content collection (e.g. posts, pages). */
+export const ocsmCollectionSchema = z.object({
+  /** Unique key, also referenced by content helpers and admin routes. */
+  name: z.string().min(1),
+  /** Human-readable label shown in the admin panel. */
+  label: z.string().min(1),
+  /** Directory (relative to the content root) holding this collection's files. */
+  directory: z.string().min(1),
+  /** URL path prefix for public routes of this collection (e.g. "blog"). */
+  basePath: z.string().optional(),
+});
+
+/** Top-level OCS Management configuration. */
+export const ocsmConfigSchema = z.object({
+  brand: ocsmBrandSchema,
+  /** Root directory (relative to the project) where content files live. */
+  contentRoot: z.string().default("content"),
+  collections: z.array(ocsmCollectionSchema).min(1),
+});

package/src/config/config.types.ts

@@ -0,0 +1,16 @@
+import type { z } from "zod";
+import type {
+  ocsmBrandSchema,
+  ocsmCollectionSchema,
+  ocsmConfigSchema,
+} from "./config.schema";
+
+/** Author-facing config shape (before defaults are applied). */
+export type OcsmConfig = z.input<typeof ocsmConfigSchema>;
+
+/** Fully-resolved config with defaults applied. */
+export type ResolvedOcsmConfig = z.output<typeof ocsmConfigSchema>;
+
+export type OcsmBrandConfig = z.input<typeof ocsmBrandSchema>;
+
+export type OcsmContentCollectionConfig = z.input<typeof ocsmCollectionSchema>;

package/src/config/define-config.ts

@@ -0,0 +1,19 @@
+import type { OcsmConfig } from "./config.types";
+
+/**
+ * Identity helper that gives full type-checking and editor autocomplete when
+ * authoring an `ocsm.config.ts` file.
+ *
+ * @example
+ * ```ts
+ * import { defineOcsmConfig } from "@orhancodestudio/ocsm-core/config";
+ *
+ * export default defineOcsmConfig({
+ *   brand: { name: "My Site" },
+ *   collections: [{ name: "posts", label: "Posts", directory: "posts", basePath: "blog" }],
+ * });
+ * ```
+ */
+export function defineOcsmConfig(config: OcsmConfig): OcsmConfig {
+  return config;
+}

package/src/config/index.ts

@@ -0,0 +1,13 @@
+export { defineOcsmConfig } from "./define-config";
+export { resolveOcsmConfig } from "./resolve-config";
+export {
+  ocsmBrandSchema,
+  ocsmCollectionSchema,
+  ocsmConfigSchema,
+} from "./config.schema";
+export type {
+  OcsmConfig,
+  OcsmBrandConfig,
+  OcsmContentCollectionConfig,
+  ResolvedOcsmConfig,
+} from "./config.types";

package/src/config/resolve-config.ts

@@ -0,0 +1,10 @@
+import { ocsmConfigSchema } from "./config.schema";
+import type { OcsmConfig, ResolvedOcsmConfig } from "./config.types";
+
+/**
+ * Validates an author-supplied config and applies defaults, returning a
+ * fully-resolved config. Throws a `ZodError` if the config is invalid.
+ */
+export function resolveOcsmConfig(config: OcsmConfig): ResolvedOcsmConfig {
+  return ocsmConfigSchema.parse(config);
+}

package/src/content/content-repository.ts

@@ -0,0 +1,66 @@
+import type { ResolvedOcsmConfig } from "../config/config.types";
+import type { FileBackend } from "../storage/file-backend";
+import {
+  CONTENT_FILE_EXTENSION,
+  type ContentStore,
+} from "./content-store.interface";
+import type {
+  ContentDocument,
+  ContentDocumentMeta,
+  WriteContentInput,
+} from "./content.types";
+import { parseDocument, serializeDocument } from "./frontmatter";
+
+/**
+ * Content access backed by a {@link FileBackend}. Maps collections to directories
+ * under the configured content root and (de)serializes MDX frontmatter.
+ */
+export class ContentRepository implements ContentStore {
+  constructor(
+    private readonly config: ResolvedOcsmConfig,
+    private readonly backend: FileBackend,
+  ) {}
+
+  async list(collection: string): Promise<ContentDocumentMeta[]> {
+    const names = await this.backend.listFiles(this.directoryFor(collection));
+    const documents: ContentDocumentMeta[] = [];
+    for (const name of names) {
+      if (!name.endsWith(CONTENT_FILE_EXTENSION)) continue;
+      const slug = name.slice(0, -CONTENT_FILE_EXTENSION.length);
+      const document = await this.read(collection, slug);
+      if (document) documents.push(document);
+    }
+    return documents;
+  }
+
+  async read(collection: string, slug: string): Promise<ContentDocument | null> {
+    const raw = await this.backend.read(this.fileFor(collection, slug));
+    if (raw === null) return null;
+    return parseDocument({ collection, slug, raw });
+  }
+
+  async write(input: WriteContentInput): Promise<void> {
+    await this.backend.write(
+      this.fileFor(input.collection, input.slug),
+      serializeDocument(input),
+      input.message ?? `ocsm: save ${input.collection}/${input.slug}`,
+    );
+  }
+
+  async delete(collection: string, slug: string): Promise<void> {
+    await this.backend.remove(
+      this.fileFor(collection, slug),
+      `ocsm: delete ${collection}/${slug}`,
+    );
+  }
+
+  private directoryFor(collection: string): string {
+    const found = this.config.collections.find((c) => c.name === collection);
+    if (!found) throw new Error(`OCSM: unknown collection "${collection}"`);
+    return `${this.config.contentRoot}/${found.directory}`;
+  }
+
+  private fileFor(collection: string, slug: string): string {
+    return `${this.directoryFor(collection)}/${slug}${CONTENT_FILE_EXTENSION}`;
+  }
+}

package/src/content/content-store.interface.ts

@@ -0,0 +1,23 @@
+import type {
+  ContentDocument,
+  ContentDocumentMeta,
+  WriteContentInput,
+} from "./content.types";
+
+/**
+ * Backend-agnostic content access. Implementations: {@link FileSystemContentStore}
+ * (local dev) and {@link GitHubContentStore} (production / serverless).
+ */
+export interface ContentStore {
+  /** Lists every document in a collection. Returns `[]` if the collection is empty. */
+  list(collection: string): Promise<ContentDocumentMeta[]>;
+  /** Reads a single document, or `null` if it does not exist. */
+  read(collection: string, slug: string): Promise<ContentDocument | null>;
+  /** Creates or updates a document. */
+  write(input: WriteContentInput): Promise<void>;
+  /** Deletes a document. No-op if it does not exist. */
+  delete(collection: string, slug: string): Promise<void>;
+}
+
+/** Shared file extension for content documents. */
+export const CONTENT_FILE_EXTENSION = ".mdx";

package/src/content/content.types.ts

@@ -0,0 +1,25 @@
+/** Metadata describing a stored content document (no body). */
+export interface ContentDocumentMeta {
+  /** Slug derived from the file name (without extension). */
+  slug: string;
+  /** Collection this document belongs to. */
+  collection: string;
+  /** Parsed frontmatter. */
+  frontmatter: Record<string, unknown>;
+}
+
+/** A full content document, including its MDX/Markdown body. */
+export interface ContentDocument extends ContentDocumentMeta {
+  /** Raw MDX/Markdown body (frontmatter stripped). */
+  body: string;
+}
+
+/** Input for creating or updating a document. */
+export interface WriteContentInput {
+  collection: string;
+  slug: string;
+  frontmatter: Record<string, unknown>;
+  body: string;
+  /** Commit message used by git-backed stores. */
+  message?: string;
+}

package/src/content/create-content-store.ts

@@ -0,0 +1,18 @@
+import type { ResolvedOcsmConfig } from "../config/config.types";
+import { createFileBackend } from "../storage/create-file-backend";
+import type { FileBackend } from "../storage/file-backend";
+import { ContentRepository } from "./content-repository";
+import type { ContentStore } from "./content-store.interface";
+
+/**
+ * Creates a {@link ContentStore} bound to the environment's storage backend
+ * (filesystem in development, GitHub in production).
+ *
+ * @param backend - Optional explicit backend, mainly for testing.
+ */
+export function createContentStore(
+  config: ResolvedOcsmConfig,
+  backend: FileBackend = createFileBackend(),
+): ContentStore {
+  return new ContentRepository(config, backend);
+}

package/src/content/frontmatter.ts

@@ -0,0 +1,25 @@
+import matter from "gray-matter";
+import type { ContentDocument } from "./content.types";
+
+/** Parses a raw MDX/Markdown string (with frontmatter) into a document. */
+export function parseDocument(params: {
+  collection: string;
+  slug: string;
+  raw: string;
+}): ContentDocument {
+  const parsed = matter(params.raw);
+  return {
+    collection: params.collection,
+    slug: params.slug,
+    frontmatter: parsed.data,
+    body: parsed.content.trim(),
+  };
+}
+
+/** Serializes frontmatter + body back into an MDX/Markdown string. */
+export function serializeDocument(input: {
+  frontmatter: Record<string, unknown>;
+  body: string;
+}): string {
+  return matter.stringify(`${input.body}\n`, input.frontmatter);
+}

package/src/content/index.ts

@@ -0,0 +1,12 @@
+export {
+  CONTENT_FILE_EXTENSION,
+  type ContentStore,
+} from "./content-store.interface";
+export type {
+  ContentDocument,
+  ContentDocumentMeta,
+  WriteContentInput,
+} from "./content.types";
+export { ContentRepository } from "./content-repository";
+export { createContentStore } from "./create-content-store";
+export { parseDocument, serializeDocument } from "./frontmatter";