Skip to content

roboticforce/yearflow

BranchesTags

Repository files navigation

YearFlow

A beautiful, interactive year-at-a-glance calendar component for high-level planning in React applications. Perfect for tracking campaigns, sprints, deadlines, and milestones across the entire year.

Live Demo | Built with love by RoboticForce

Screenshots

Year View

Year View

Week View with Events

Week View with Events

Week View

Week View

Features

  • Multiple View Modes - Year, Quarter, and Week views for different levels of detail
  • Date Range Events - Create events that span multiple days (trips, projects, campaigns)
  • Sticky Notes - Add quick notes to specific dates
  • Blocked Days - Mark days as unavailable with custom categories
  • Customizable Legend - Define your own categories with colors (Recruiting, Sprints, Deadlines, etc.)
  • Drag & Drop - Easily move notes between dates
  • Theme Customization - Customize colors, fonts, shadows, and border radius
  • Persistence Adapters - Built-in support for localStorage, API backends, or custom storage solutions
  • TypeScript Support - Fully typed with comprehensive type definitions
  • Rails Integration - Stimulus controller for seamless Rails integration

Installation

npm install yearflow

or

yarn add yearflow

Quick Start

import { YearPlanner } from 'yearflow';
import 'yearflow/styles.css';

function App() {
  return <YearPlanner year={2026} />;
}

Props Reference

Prop Type Default Description
year number Current year The year to display
initialView 'year' | 'quarter' | 'week' 'year' Initial view mode
weekStartsOn 0 | 1 | 6 1 Day to start the week (0=Sunday, 1=Monday, 6=Saturday)
persistenceAdapter PersistenceAdapter localStorage Storage adapter for loading/saving data
initialData Partial<PlannerData> {} Initial data to populate the planner
theme Partial<PlannerTheme> Default theme Theme overrides for colors, fonts, etc.
colorPalette ColorPalette Built-in palette Available colors for legend items
labels Partial<PlannerLabels> Default English Custom labels for i18n / text customization
className string '' Additional CSS class
features object All enabled Feature flags to enable/disable functionality
onBlockDay (date, category) => void - Callback when a day is blocked
onClearDay (date) => void - Callback when a day is cleared
onAddNote (note) => void - Callback when a note is added
onDeleteNote (noteId) => void - Callback when a note is deleted
onUpdateNote (note) => void - Callback when a note is updated
onAddEvent (event) => void - Callback when an event is added
onUpdateEvent (event) => void - Callback when an event is updated
onDeleteEvent (eventId) => void - Callback when an event is deleted
onLegendChange (legend) => void - Callback when legend items are modified
onDataChange (data) => void - Callback when any data changes
onViewChange (view) => void - Callback when view mode changes

Feature Flags

features?: {
  enableNotes?: boolean;          // Default: true
  enablePrint?: boolean;          // Default: true
  enableLegendEdit?: boolean;     // Default: true
  enableLegendReorder?: boolean;  // Default: true
  enableLegendAdd?: boolean;      // Default: true
  enableLegendDelete?: boolean;   // Default: true
  enableDragDrop?: boolean;       // Default: true
}

Labels / i18n Customization

Customize all user-facing text for internationalization or personalization:

import { YearPlanner } from 'yearflow';
import 'yearflow/styles.css';

const spanishLabels = {
  header: {
    title: 'Planificador Anual',
    viewYear: 'Año',
    viewQuarter: 'Trimestre',
    viewWeek: 'Semana',
    quarterOptions: [
      'T1 (Ene - Mar)',
      'T2 (Abr - Jun)',
      'T3 (Jul - Sep)',
      'T4 (Oct - Dic)',
    ],
  },
  eventModal: {
    titleAdd: 'Añadir Evento',
    titleEdit: 'Editar Evento',
    labelTitle: 'Título',
    labelStartDate: 'Fecha de Inicio',
    labelEndDate: 'Fecha de Fin',
    labelCategory: 'Categoría',
    labelDescription: 'Descripción (opcional)',
    placeholderTitle: 'ej. Sprint de Q1, Campaña de reclutamiento...',
    buttonSave: 'Guardar',
    buttonCancel: 'Cancelar',
    buttonAdd: 'Añadir Evento',
    buttonDelete: 'Eliminar',
  },
  legend: {
    title: 'Categorías',
    addButtonTitle: 'Añadir categoría',
    placeholderCategoryName: 'Nombre de categoría...',
  },
  notesPanel: {
    title: 'Notas y Metas',
    emptyDefault: 'Sin notas. ¡Añade una para comenzar!',
    buttonAdd: '+ Añadir Nota',
  },
  eventsPanel: {
    title: 'Eventos',
    empty: 'Sin eventos. ¡Haz clic en un día para añadir uno!',
    buttonAdd: '+ Añadir Evento',
  },
  weekView: {
    weekOfFormat: 'Semana del {day} de {month}, {year}',
    prevWeek: '← Semana Anterior',
    nextWeek: 'Próxima Semana →',
    monthAbbreviations: [
      'Ene', 'Feb', 'Mar', 'Abr', 'May', 'Jun',
      'Jul', 'Ago', 'Sep', 'Oct', 'Nov', 'Dic',
    ],
  },
  general: {
    loading: 'Cargando...',
  },
};

function App() {
  return <YearPlanner year={2026} labels={spanishLabels} />;
}

Available Label Sections

Section Description
header Title, view buttons, quarter dropdown options
eventModal Event modal title, form labels, placeholders, buttons
addNoteModal Note modal title, form labels, placeholders, buttons
blockDayModal Block day modal labels and buttons
legend Legend panel title, add button, category placeholder
notesPanel Notes panel title, empty states, add button
eventsPanel Events panel title, empty state, add button
weekView Week header format, navigation buttons, month abbreviations
calendarGrid Add event button title, overflow text
eventBar Event overflow indicator text
general Loading text

Accessing Default Labels

import { defaultLabels, mergeLabels } from 'yearflow';

// Get all default labels
console.log(defaultLabels);

// Merge partial custom labels with defaults
const customLabels = mergeLabels({
  header: { title: 'My Calendar' },
});

Theme Customization

Customize the appearance by providing a theme object:

import { YearPlanner } from 'yearflow';
import 'yearflow/styles.css';

const customTheme = {
  colors: {
    primary: '#4a90e2',
    background: '#ffffff',
    surface: '#f8f9fa',
    text: '#212529',
    textSecondary: '#6c757d',
    textMuted: '#adb5bd',
    border: '#dee2e6',
    weekend: '#f1f3f5',
  },
  fonts: {
    sans: "'Inter', sans-serif",
    serif: "'Merriweather', serif",
  },
  radius: {
    sm: '4px',
    md: '8px',
    lg: '12px',
  },
  shadows: {
    sm: '0 1px 3px rgba(0,0,0,0.1)',
    md: '0 4px 8px rgba(0,0,0,0.1)',
    lg: '0 10px 20px rgba(0,0,0,0.1)',
  },
};

function App() {
  return <YearPlanner year={2026} theme={customTheme} />;
}

Custom Color Palette

Define your own color palette for legend items:

const customColors = [
  { id: 'ocean-blue', value: '#0077be', name: 'Ocean Blue' },
  { id: 'sunset-orange', value: '#ff6b35', name: 'Sunset Orange' },
  { id: 'forest-green', value: '#2d6a4f', name: 'Forest Green' },
  { id: 'lavender', value: '#9d84b7', name: 'Lavender' },
];

const customLegend = [
  { id: 'recruiting', label: 'Recruiting', colorId: 'ocean-blue', order: 0 },
  { id: 'sprints', label: 'Engineering Sprints', colorId: 'sunset-orange', order: 1 },
  { id: 'onboarding', label: 'Onboarding', colorId: 'forest-green', order: 2 },
  { id: 'deadlines', label: 'Deadlines', colorId: 'lavender', order: 3 },
];

function App() {
  return (
    <YearPlanner
      year={2026}
      colorPalette={customColors}
      initialData={{ legend: customLegend }}
    />
  );
}

Persistence Adapters

LocalStorage (Default)

Automatically saves data to browser localStorage:

import { YearPlanner, localStorageAdapter } from 'yearflow';

function App() {
  return (
    <YearPlanner
      year={2026}
      persistenceAdapter={localStorageAdapter('myPlanner2026')}
    />
  );
}

API Backend

Save data to your backend API:

import { YearPlanner, apiAdapter } from 'yearflow';

function App() {
  return (
    <YearPlanner
      year={2026}
      persistenceAdapter={apiAdapter('/api/planner', 'your-auth-token')}
    />
  );
}

The API adapter expects:

  • GET /api/planner - Returns PlannerData JSON
  • PUT /api/planner - Accepts PlannerData JSON in request body

Custom Adapter

Implement your own persistence logic:

const customAdapter = {
  async load() {
    // Load data from your storage
    const data = await yourCustomLoadFunction();
    return data;
  },
  async save(data) {
    // Save data to your storage
    await yourCustomSaveFunction(data);
  },
};

function App() {
  return <YearPlanner year={2026} persistenceAdapter={customAdapter} />;
}

No Persistence (Controlled Mode)

Use noopAdapter to fully control data externally:

import { YearPlanner, noopAdapter } from 'yearflow';

function App() {
  const [plannerData, setPlannerData] = useState(initialData);

  return (
    <YearPlanner
      year={2026}
      persistenceAdapter={noopAdapter}
      initialData={plannerData}
      onDataChange={setPlannerData}
    />
  );
}

Initial Data

Provide initial events, notes, and blocked days:

const initialData = {
  events: [
    {
      id: '1',
      title: 'Q3 Recruiting Push',
      startDate: '2026-07-01',
      endDate: '2026-07-14',
      category: 'default-green',
      description: 'Engineering team expansion',
    },
  ],
  notes: [
    {
      id: '1',
      title: 'Review job postings',
      date: '2026-06-01',
      category: 'default-blue',
    },
  ],
  blockedDays: {
    '2026-12-25': 'default-red',
    '2026-12-26': 'default-red',
  },
  legend: [
    { id: 'default-green', label: 'Recruiting', colorId: 'green', order: 0 },
    { id: 'default-blue', label: 'Sprints', colorId: 'blue', order: 1 },
    { id: 'default-red', label: 'Company Events', colorId: 'red', order: 2 },
  ],
};

function App() {
  return <YearPlanner year={2026} initialData={initialData} />;
}

Rails Integration

A Stimulus controller is available for seamless Rails integration. See the /integrations/rails directory for:

  • yearflow_controller.js - Stimulus controller
  • README.md - Rails integration guide

Example Rails setup:

<!-- app/views/planners/show.html.erb -->
<div data-controller="yearflow"
     data-yearflow-year-value="2026"
     data-yearflow-api-url-value="/api/planner">
</div>

Advanced Usage

Using Hooks and Context

For custom layouts or advanced integration, you can use the underlying hooks and components:

import {
  PlannerProvider,
  usePlanner,
  Header,
  CalendarGrid,
  Sidebar,
} from 'yearflow';

function CustomPlanner() {
  const { state, actions } = usePlanner();

  return (
    <div>
      <Header year={2026} />
      <div style={{ display: 'flex' }}>
        <CalendarGrid year={2026} />
        <Sidebar />
      </div>
      <pre>{JSON.stringify(state, null, 2)}</pre>
    </div>
  );
}

function App() {
  return (
    <PlannerProvider>
      <CustomPlanner />
    </PlannerProvider>
  );
}

Exported Components

All major components are exported for custom layouts:

  • YearPlanner - Main component
  • Header - Header with view controls
  • CalendarGrid - Month grid for year/quarter view
  • WeekView - Week detail view
  • Sidebar - Sidebar with legend, notes, and events
  • MonthCard - Individual month component
  • DayCell - Individual day cell
  • And more...

TypeScript

The library includes comprehensive TypeScript definitions. Key types:

import type {
  YearPlannerProps,
  PlannerData,
  PlannerEvent,
  Note,
  Legend,
  LegendItem,
  ColorPalette,
  PlannerTheme,
  PersistenceAdapter,
  ViewMode,
  // Labels / i18n types
  PlannerLabels,
  HeaderLabels,
  EventModalLabels,
  AddNoteModalLabels,
  BlockDayModalLabels,
  LegendLabels,
  NotesPanelLabels,
  EventsPanelLabels,
  WeekViewLabels,
  CalendarGridLabels,
  EventBarLabels,
  GeneralLabels,
  DeepPartial,
} from 'yearflow';

License

MIT

More from RoboticForce

YearFlow is part of the RoboticForce ecosystem of developer tools and services:

  • Sugar - A dev team that never stops. Delegate full tasks to AI in the background.
  • RoboticForce - Open source AI tools and autonomous agent development

Building something with AI? Let's talk.

Repository

https://github.com/roboticforce/yearflow

About

A beautiful year-at-a-glance planner component for React.

yearflow.roboticforce.io

Topics

react events typescript planner calendar scheduler react-component planning date-picker year-planner

Resources

Readme

License

MIT license
Activity
Custom properties

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases 4

v0.2.0 - Labels / i18n Customization Latest
Dec 22, 2025
+ 3 releases

Packages

No packages published

Languages