@jjlmoya/utils-nautical 1.2.0

package/src/tool/tideCalculator/component.astro

@@ -0,0 +1,314 @@
+---
+import './style.css';
+import type { TideCalculatorUI } from './index';
+
+interface Props {
+  ui: TideCalculatorUI;
+}
+
+const { ui } = Astro.props;
+---
+
+<section id="tide-calculator" class="tide-calculator" data-ui={JSON.stringify(ui)}>
+    <div class="tc-main-card">
+        <div class="tc-calc-sidebar">
+            <div class="tc-sidebar-header">
+                <h3>{ui.parametersLabel}</h3>
+                <button id="invert-btn" title="Invertir ciclo">
+                    <svg viewBox="0 0 24 24" width="20" height="20"><path fill="currentColor" d="M18 18V22H16V18H13L17 14L21 18H18M8 6V2H10V6H13L9 10L5 6H8M3 15V13H5V15H3M3 11V9H5V11H3M3 7V5H5V7H3M19 11V9H21V11H19M19 15V13H21V15H19M19 19V17H21V19H19M3 19V17H5V19H3Z"/></svg>
+                </button>
+            </div>
+
+            <div class="tc-input-set">
+                <div class="tc-input-block">
+                    <label>{ui.highTideLabel}</label>
+                    <div class="row">
+                        <input type="time" id="high-tide-time" value="12:00" />
+                        <div class="tc-unit-input">
+                            <input type="number" id="high-tide-height" value="3.5" step="0.1" />
+                            <span>m</span>
+                        </div>
+                    </div>
+                </div>
+
+                <div class="tc-input-block">
+                    <label>{ui.lowTideLabel}</label>
+                    <div class="row">
+                        <input type="time" id="low-tide-time" value="06:00" />
+                        <div class="tc-unit-input">
+                            <input type="number" id="low-tide-height" value="0.5" step="0.1" />
+                            <span>m</span>
+                        </div>
+                    </div>
+                </div>
+
+                <div class="tc-input-block tc-featured">
+                    <label>{ui.targetTimeLabel}</label>
+                    <input type="time" id="target-time" value="09:00" class="large-time" />
+                </div>
+            </div>
+        </div>
+
+        <div class="tc-calc-content">
+            <div class="tc-top-row">
+                <div class="tc-result-display">
+                    <span class="label">{ui.estimatedHeightLabel}</span>
+                    <div class="tc-value-box">
+                        <span id="target-value">--</span>
+                        <small>{ui.metersLabel}</small>
+                    </div>
+                    <span id="tide-status" class="tc-status-indicator">--</span>
+                </div>
+                <div class="tc-summary-info">
+                    <div class="tc-stat">
+                        <span class="tc-s-label">{ui.amplitudeLabel}</span>
+                        <span id="amplitude-val">--</span>
+                    </div>
+                    <div class="tc-stat">
+                        <span class="tc-s-label">{ui.durationLabel}</span>
+                        <span id="duration-val">--</span>
+                    </div>
+                </div>
+            </div>
+
+            <div class="tc-chart-area">
+                <canvas id="tide-chart"></canvas>
+            </div>
+        </div>
+    </div>
+
+    <div class="tc-table-card">
+        <h4>{ui.tableBreakdownLabel}</h4>
+        <div class="tc-table-wrapper">
+            <table id="twelfths-table">
+                <thead>
+                    <tr>
+                        <th>{ui.tableHourLabel}</th>
+                        <th>{ui.tableStateLabel}</th>
+                        <th>%</th>
+                        <th>{ui.metersLabel}</th>
+                    </tr>
+                </thead>
+                <tbody></tbody>
+            </table>
+        </div>
+    </div>
+</section>
+
+<script>
+    import { Chart, registerables } from 'chart.js';
+    Chart.register(...registerables);
+
+    const section = document.getElementById('tide-calculator') as HTMLElement;
+    const ui = JSON.parse(section.dataset.ui as string);
+
+    interface CycleState { sT: number; dur: number; amp: number; sH: number; mult: number; }
+    type Pt = { t: number; h: number; p: string };
+
+    class TideCalculator {
+        private highTime: HTMLInputElement;
+        private highHeight: HTMLInputElement;
+        private lowTime: HTMLInputElement;
+        private lowHeight: HTMLInputElement;
+        private targetTime: HTMLInputElement;
+        private invertBtn: HTMLElement;
+        private displayValue: HTMLElement;
+        private displayStatus: HTMLElement;
+        private displayAmp: HTMLElement;
+        private displayDur: HTMLElement;
+        private tableBody: HTMLElement;
+        private chart: InstanceType<typeof Chart>;
+
+        constructor() {
+            this.highTime = document.getElementById('high-tide-time') as HTMLInputElement;
+            this.highHeight = document.getElementById('high-tide-height') as HTMLInputElement;
+            this.lowTime = document.getElementById('low-tide-time') as HTMLInputElement;
+            this.lowHeight = document.getElementById('low-tide-height') as HTMLInputElement;
+            this.targetTime = document.getElementById('target-time') as HTMLInputElement;
+            this.invertBtn = document.getElementById('invert-btn') as HTMLElement;
+            this.displayValue = document.getElementById('target-value') as HTMLElement;
+            this.displayStatus = document.getElementById('tide-status') as HTMLElement;
+            this.displayAmp = document.getElementById('amplitude-val') as HTMLElement;
+            this.displayDur = document.getElementById('duration-val') as HTMLElement;
+            this.tableBody = document.querySelector('#twelfths-table tbody') as HTMLElement;
+            this.chart = this.initChart();
+            this.init();
+        }
+
+        private init() {
+            [this.highTime, this.highHeight, this.lowTime, this.lowHeight, this.targetTime].forEach(
+                (i) => i.addEventListener('input', () => this.calculate()),
+            );
+            this.invertBtn.addEventListener('click', () => this.invert());
+            this.calculate();
+        }
+
+        private invert() {
+            const hT = this.highTime.value;
+            const hH = this.highHeight.value;
+            this.highTime.value = this.lowTime.value;
+            this.highHeight.value = this.lowHeight.value;
+            this.lowTime.value = hT;
+            this.lowHeight.value = hH;
+            this.calculate();
+        }
+
+        private timeToMins(s: string) {
+            const [h, m] = s.split(':').map(Number);
+            return h * 60 + m;
+        }
+
+        private minsToTime(m: number) {
+            let mins = Math.round(m) % 1440;
+            if (mins < 0) mins += 1440;
+            return `${String(Math.floor(mins / 60)).padStart(2, '0')}:${String(mins % 60).padStart(2, '0')}`;
+        }
+
+        private calculate() {
+            const tH = this.timeToMins(this.highTime.value);
+            const hH = parseFloat(this.highHeight.value);
+            const tL = this.timeToMins(this.lowTime.value);
+            const hL = parseFloat(this.lowHeight.value);
+            const tT = this.timeToMins(this.targetTime.value);
+            if (isNaN(hH) || isNaN(hL)) return;
+            const isFlooding = tH > tL;
+            const state: CycleState = {
+                sT: isFlooding ? tL : tH,
+                dur: Math.abs(tH - tL),
+                amp: Math.abs(hH - hL),
+                sH: isFlooding ? hL : hH,
+                mult: isFlooding ? 1 : -1,
+            };
+            this.displayAmp.textContent = `${state.amp.toFixed(2)} m`;
+            this.displayDur.textContent = `${Math.floor(state.dur / 60)}h ${state.dur % 60}m`;
+            const pts = this.generateCycle(state);
+            this.updateUI(pts, tT, state);
+        }
+
+        private generateCycle(state: CycleState): Pt[] {
+            const { sT, dur, amp, sH, mult } = state;
+            const step = dur / 6;
+            const doz = [1 / 12, 2 / 12, 3 / 12, 3 / 12, 2 / 12, 1 / 12];
+            const pts: Pt[] = [{ t: sT, h: sH, p: '0%' }];
+            let cum = 0;
+            for (let i = 0; i < 6; i++) {
+                cum += doz[i];
+                pts.push({ t: sT + step * (i + 1), h: sH + cum * amp * mult, p: `${Math.round(cum * 100)}%` });
+            }
+            return pts;
+        }
+
+        private getRowLabel(i: number): string {
+            if (i === 0) return ui.tableStartLabel;
+            if (i === 6) return ui.tableEndLabel;
+            return '---';
+        }
+
+        private updateStatus(tT: number, state: CycleState) {
+            const { sT, dur, amp, sH, mult } = state;
+            const rel = tT - sT;
+            if (rel >= 0 && rel <= dur) {
+                const step = dur / 6;
+                const idx = Math.floor(rel / step);
+                const doz = [1 / 12, 2 / 12, 3 / 12, 3 / 12, 2 / 12, 1 / 12];
+                let cum = 0;
+                for (let i = 0; i < idx; i++) cum += doz[i];
+                const rem = (rel % step) / step;
+                const h = sH + (cum + (idx < 6 ? (doz[idx] ?? 0) : 0) * rem) * amp * mult;
+                this.displayValue.textContent = h.toFixed(2);
+                this.displayStatus.textContent = mult > 0 ? ui.statusUpLabel : ui.statusDownLabel;
+                this.displayStatus.className = `tc-status-indicator ${mult > 0 ? 'up' : 'down'}`;
+            } else {
+                this.displayValue.textContent = '--';
+                this.displayStatus.textContent = ui.statusOutOfRange;
+                this.displayStatus.className = 'tc-status-indicator';
+            }
+        }
+
+        private updateTable(pts: Pt[]) {
+            this.tableBody.innerHTML = pts
+                .map((p, i) => `<tr>
+                    <td>${this.minsToTime(p.t)}</td>
+                    <td>${this.getRowLabel(i)}</td>
+                    <td>${p.p}</td>
+                    <td>${p.h.toFixed(2)}m</td>
+                </tr>`)
+                .join('');
+        }
+
+        private updateUI(pts: Pt[], tT: number, state: CycleState) {
+            this.updateStatus(tT, state);
+            this.updateTable(pts);
+            this.updateChart(pts, tT, state);
+        }
+
+        private getChartDatasets() {
+            return [
+                {
+                    data: [] as number[],
+                    borderColor: '#0074B7',
+                    borderWidth: 3,
+                    pointRadius: 0,
+                    tension: 0.4,
+                    fill: true,
+                    backgroundColor: (context: { chart: { ctx: CanvasRenderingContext2D; chartArea: { top: number; bottom: number } } }) => {
+                        const { ctx: c, chartArea } = context.chart;
+                        if (!chartArea) return undefined;
+                        const g = c.createLinearGradient(0, chartArea.top, 0, chartArea.bottom);
+                        g.addColorStop(0, 'rgba(0, 116, 183, 0.2)');
+                        g.addColorStop(1, 'rgba(0, 116, 183, 0)');
+                        return g;
+                    },
+                },
+                {
+                    data: [] as object[],
+                    pointRadius: 6,
+                    pointBackgroundColor: '#FF6B35',
+                    pointBorderColor: '#ffffff',
+                    pointBorderWidth: 2,
+                    showLine: false,
+                },
+            ];
+        }
+
+        private initChart() {
+            const ctx = document.getElementById('tide-chart') as HTMLCanvasElement;
+            return new Chart(ctx, {
+                type: 'line',
+                data: { labels: [], datasets: this.getChartDatasets() },
+                options: {
+                    responsive: true,
+                    maintainAspectRatio: false,
+                    plugins: { legend: { display: false } },
+                    scales: {
+                        x: { display: false },
+                        y: { display: true, grid: { color: 'rgba(0,0,0,0.05)' } },
+                    },
+                },
+            });
+        }
+
+        private updateChart(pts: Pt[], tT: number, state: CycleState) {
+            const { sT, dur, amp, sH, mult } = state;
+            const labels = pts.map((p) => this.minsToTime(p.t));
+            this.chart.data.labels = labels;
+            this.chart.data.datasets[0].data = pts.map((p) => p.h);
+            const rel = tT - sT;
+            if (rel >= 0 && rel <= dur) {
+                const step = dur / 6;
+                const idx = Math.floor(rel / step);
+                const doz = [1 / 12, 2 / 12, 3 / 12, 3 / 12, 2 / 12, 1 / 12];
+                let cum = 0;
+                for (let i = 0; i < idx; i++) cum += doz[i];
+                const rem = (rel % step) / step;
+                const h = sH + (cum + (idx < 6 ? (doz[idx] ?? 0) : 0) * rem) * amp * mult;
+                this.chart.data.datasets[1].data = [{ x: labels[Math.round(rel / step)], y: h }];
+            } else {
+                this.chart.data.datasets[1].data = [];
+            }
+            this.chart.update();
+        }
+    }
+
+    new TideCalculator();
+</script>

package/src/tool/tideCalculator/i18n/en.ts

@@ -0,0 +1,203 @@
+import type { WithContext, FAQPage, HowTo, SoftwareApplication } from 'schema-dts';
+import type { TideCalculatorUI, TideCalculatorLocaleContent } from '../index';
+
+const slug = 'tide-height-calculator';
+const title = 'Tide Height Calculator';
+const description =
+  'Estimate water depth at any point in the tidal cycle using the nautical Rule of Twelfths. Ideal for coastal planning and nautical licence study.';
+
+const ui: TideCalculatorUI = {
+  parametersLabel: 'Parameters',
+  highTideLabel: 'High Tide',
+  lowTideLabel: 'Low Tide',
+  targetTimeLabel: 'Query time',
+  estimatedHeightLabel: 'Estimated Height',
+  metersLabel: 'metres',
+  amplitudeLabel: 'Amplitude',
+  durationLabel: 'Duration',
+  tableBreakdownLabel: 'Twelfths Breakdown',
+  tableHourLabel: 'Time',
+  tableStateLabel: 'State',
+  tableStartLabel: 'Start',
+  tableEndLabel: 'End',
+  statusUpLabel: 'Rising',
+  statusDownLabel: 'Falling',
+  statusOutOfRange: 'Out of range',
+  faqTitle: 'Frequently Asked Questions',
+  bibliographyTitle: 'Bibliography',
+};
+
+const faq: TideCalculatorLocaleContent['faq'] = [
+  {
+    question: 'What is the Rule of Twelfths and what is it used for?',
+    answer:
+      'The Rule of Twelfths is a simplified mathematical method used in navigation to estimate the tide height at any point between high and low water. It is based on the observation that tidal flow follows an approximate sinusoidal curve, dividing the total range into 12 parts over 6 hours (1/12, 2/12, 3/12, 3/12, 2/12, 1/12).',
+  },
+  {
+    question: 'Is this method reliable for real navigation?',
+    answer:
+      'It is a very useful theoretical estimation method for quick planning and educational purposes. However, it does not account for meteorological factors such as atmospheric pressure or wind, which can alter sea level by several decimetres. For real navigation, always consult official tide tables.',
+  },
+  {
+    question: 'What data do I need to calculate tide height?',
+    answer:
+      'You need the time and height (in metres) of the high tide and low tide closest to the moment you wish to query. This data is found in tide almanacs or marine weather applications.',
+  },
+  {
+    question: 'Why does the tide not always rise at the same speed?',
+    answer:
+      'Due to the inertia of large water masses and the configuration of ocean basins. The tide begins to rise slowly after low water, reaches maximum speed in the middle hours (the 3/12 hours) and slows again as it approaches high water.',
+  },
+  {
+    question: 'How does atmospheric pressure affect the tide?',
+    answer:
+      'High pressure (anticyclone) pushes water down, reducing the actual height. Low pressure (depression) allows water to rise higher. As a general rule, a variation of 1 hPa from the mean corresponds to approximately 1 cm change in sea level.',
+  },
+  {
+    question: 'What is tidal range?',
+    answer:
+      'It is the vertical difference in height between a high tide and the immediately preceding or following low tide. This measurement varies according to lunar phase (spring and neap tides) and geographical location.',
+  },
+];
+
+const howTo: TideCalculatorLocaleContent['howTo'] = [
+  {
+    name: 'Identify high and low tide',
+    text: 'Consult your tide almanac to obtain the times and heights for the tidal cycle you are interested in.',
+  },
+  {
+    name: 'Enter the data in the calculator',
+    text: 'Input the time and height of high tide and low tide. The tool will determine duration and amplitude automatically.',
+  },
+  {
+    name: 'Set the query time',
+    text: 'Adjust the time for which you want to know the water level. You will see the exact point highlighted on the chart.',
+  },
+  {
+    name: 'Analyse the twelfths table',
+    text: 'Review the hour-by-hour breakdown to understand how the water level will fluctuate throughout the entire period.',
+  },
+];
+
+const bibliography: TideCalculatorLocaleContent['bibliography'] = [
+  {
+    name: 'Puertos del Estado - Tide Prediction',
+    url: 'https://portus.puertos.es/#/',
+  },
+  {
+    name: 'Instituto Hidrografico de la Marina',
+    url: 'https://armada.defensa.gob.es/ihm/',
+  },
+];
+
+const seo: TideCalculatorLocaleContent['seo'] = [
+  {
+    type: 'title',
+    text: 'Mastering the Tide: The Rule of Twelfths in Navigation',
+    level: 2,
+  },
+  {
+    type: 'paragraph',
+    html: 'Coastal navigation and entering harbours with restricted depth require precise knowledge of water depth at all times. Although digital applications and GPS providing real-time data are available today, the <strong>Rule of Twelfths</strong> remains a fundamental tool in the training of any recreational craft skipper or yacht captain. This rule is a mathematical estimation method that allows you to calculate, approximately and without complex calculators, the tide height at any point in a tidal cycle.',
+  },
+  {
+    type: 'title',
+    text: 'What exactly is the Rule of Twelfths?',
+    level: 3,
+  },
+  {
+    type: 'paragraph',
+    html: 'The Rule of Twelfths is based on the observation that tidal flow is not constant. Water does not rise or fall at the same speed during the approximately six hours between high water and low water. Instead, the movement follows a sinusoidal curve. During the first hour the tide moves slowly; it accelerates in the middle hours and slows again as it approaches the next extreme.',
+  },
+  {
+    type: 'table',
+    headers: ['Hour of Cycle', 'Proportion', 'Flow State'],
+    rows: [
+      ['<strong>1st Hour</strong>', '1/12 of the range', 'Slow start (Slack water)'],
+      ['<strong>2nd Hour</strong>', '2/12 of the range', 'Accelerating flow'],
+      ['<strong>3rd Hour</strong>', '3/12 of the range', 'Maximum flow (Strong current)'],
+      ['<strong>4th Hour</strong>', '3/12 of the range', 'Sustained flow'],
+      ['<strong>5th Hour</strong>', '2/12 of the range', 'Notable deceleration'],
+      ['<strong>6th Hour</strong>', '1/12 of the range', 'Final slowing (Towards slack water)'],
+    ],
+  },
+  {
+    type: 'title',
+    text: 'Technical limitations: Factors affecting the real tide',
+    level: 3,
+  },
+  {
+    type: 'glossary',
+    items: [
+      { term: 'Atmospheric pressure', definition: 'A depression raises sea level; an anticyclone lowers it. As a general rule, ~1 cm variation per hPa difference from the mean.' },
+      { term: 'Coastal wind', definition: 'Sustained onshore winds can pile water above predicted levels in the tide tables.' },
+      { term: 'Local topography', definition: 'Coastal shape, seabed depth and the presence of estuaries can significantly delay or accelerate tidal flow.' },
+    ],
+  },
+  {
+    type: 'tip',
+    title: 'Safety Note',
+    html: 'This tool uses a mathematical estimation method. It does not account for meteorological factors or local topography. For real navigation, always consult the official tide tables.',
+  },
+  {
+    type: 'title',
+    text: 'Key concepts for new sailors',
+    level: 3,
+  },
+  {
+    type: 'glossary',
+    items: [
+      {
+        term: 'Tidal range',
+        definition: 'Vertical difference between high water and low water. In the Bay of Biscay it can be several metres; in the Mediterranean it is almost negligible.',
+      },
+      {
+        term: 'Tidal duration',
+        definition: 'Time interval between high water and the next low water. Typically around 6 hours and 12 minutes (semi-diurnal cycle).',
+      },
+      {
+        term: 'Chart datum',
+        definition: 'Reference level from which all depths on nautical charts are measured. Actual depths are almost never less than those indicated.',
+      },
+    ],
+  },
+];
+
+const schemas: TideCalculatorLocaleContent['schemas'] = [
+  {
+    '@context': 'https://schema.org',
+    '@type': 'SoftwareApplication',
+    name: title,
+    description,
+    applicationCategory: 'UtilityApplication',
+    operatingSystem: 'Web',
+    offers: { '@type': 'Offer', price: '0', priceCurrency: 'EUR' },
+  } as WithContext<SoftwareApplication>,
+  {
+    '@context': 'https://schema.org',
+    '@type': 'FAQPage',
+    mainEntity: faq.map((item) => ({
+      '@type': 'Question',
+      name: item.question,
+      acceptedAnswer: { '@type': 'Answer', text: item.answer },
+    })),
+  } as WithContext<FAQPage>,
+  {
+    '@context': 'https://schema.org',
+    '@type': 'HowTo',
+    name: `How to use: ${title}`,
+    step: howTo.map((s) => ({ '@type': 'HowToStep', name: s.name, text: s.text })),
+  } as WithContext<HowTo>,
+];
+
+export const content: TideCalculatorLocaleContent = {
+  slug,
+  title,
+  description,
+  ui,
+  seo,
+  faq,
+  bibliography,
+  howTo,
+  schemas,
+};