ExternalLink.cs

/*
 * NanoXLSX is a small .NET library to generate and read XLSX (Microsoft Excel 2007 or newer) files in an easy and native way  
 * Copyright Raphael Stoeckli © 2026
 * This library is licensed under the MIT License.
 * You find a copy of the license in project folder or on: http://opensource.org/licenses/MIT
 */
 
using System;
using System.Collections.Generic;
using System.Linq;
 
namespace NanoXLSX
{
    public class ExternalLink
    {
        private readonly List<ExternalWorksheet> worksheets = new List<ExternalWorksheet>();
        private readonly List<ExternalDefinedName> definedNames = new List<ExternalDefinedName>();
        public string AbsoluteUri { get; private set; }

        public string RelativeUri { get; private set; }

        internal string TargetUri { get; private set; }

        internal string AbsoluteAlternateUri { get; private set; }

        internal string RelativeAlternateUri { get; private set; }

        public IReadOnlyList<ExternalWorksheet> Worksheets => worksheets;

        public IReadOnlyList<ExternalDefinedName> DefinedNames => definedNames;

        internal string WorkbookRId { get; set; }

        internal string ReadableReferenceToken
        {
            get
            {
                string uri = GetReadableUri();
                if (!string.IsNullOrEmpty(uri))
                {
                    return "[" + uri + "]";
                }
                return null;
            }
        }

        internal ExternalLink()
        {
        }

        public ExternalLink(string absoluteUri)
        {
            SetAuthoringUris(absoluteUri, null);
        }

        public ExternalLink(string absoluteUri, string relativeUri)
        {
            SetAuthoringUris(absoluteUri, relativeUri);
        }
 

        public ExternalLinkBuilder CreateBuilder()
        {
            return new ExternalLinkBuilder(this);
        }

        public void AddDefinedName(string name, string refersTo)
        {
            AddDefinedName(new ExternalDefinedName(name, refersTo));
        }

        public void AddDefinedName(ExternalDefinedName definedName)
        {
            if (definedName == null)
            {
                throw new ArgumentException("An external defined name cannot be null");
            }
 
            if (definedNames.Any(
                    item => string.Equals(
                        item.Name,
                        definedName.Name,
                        StringComparison.OrdinalIgnoreCase)))
            {
                throw new ArgumentException($"The external defined name '{definedName.Name}' already exists.");
            }
            definedNames.Add(definedName);
        }

        private void SetAuthoringUris(string absoluteUri, string relativeUri)
        {
            ValidateWorkbookLocation(absoluteUri, true);
            if (relativeUri != null)
            {
                ValidateWorkbookLocation(relativeUri, false);
            }
 
            AbsoluteUri = absoluteUri;
            RelativeUri = relativeUri;
            TargetUri = relativeUri ?? absoluteUri;
            AbsoluteAlternateUri = relativeUri == null ? null : absoluteUri;
            RelativeAlternateUri = null;
        }

        internal void SetReadUris(string targetUri, string absoluteAlternateUri, string relativeAlternateUri)
        {
            ValidateWorkbookLocation(targetUri, null);
            if (absoluteAlternateUri != null)
            {
                ValidateWorkbookLocation(absoluteAlternateUri, true);
            }
            if (relativeAlternateUri != null)
            {
                ValidateWorkbookLocation(relativeAlternateUri, false);
            }
 
            TargetUri = targetUri;
            AbsoluteAlternateUri = absoluteAlternateUri;
            RelativeAlternateUri = relativeAlternateUri;
 
            bool targetIsAbsolute = IsAbsoluteWorkbookLocation(targetUri);
            AbsoluteUri = targetIsAbsolute ? targetUri : absoluteAlternateUri;
            RelativeUri = targetIsAbsolute ? relativeAlternateUri : targetUri;
        }

        internal IReadOnlyList<string> GetWorkbookLocations()
        {
            List<string> locations = new List<string>();
            AddDistinctLocation(locations, TargetUri);
            AddDistinctLocation(locations, AbsoluteAlternateUri);
            AddDistinctLocation(locations, RelativeAlternateUri);
            return locations.AsReadOnly();
        }

        internal IReadOnlyList<ExternalLinkUriRelationship> GetUriRelationships()
        {
            List<ExternalLinkUriRelationship> relationships = new List<ExternalLinkUriRelationship>();
            relationships.Add(new ExternalLinkUriRelationship(
                "rId1",
                TargetUri,
                SerializeRelationshipTarget(TargetUri),
                ExternalLinkUriRole.Target));
 
            int relationshipIndex = 2;
            if (AbsoluteAlternateUri != null)
            {
                relationships.Add(new ExternalLinkUriRelationship(
                    "rId" + relationshipIndex,
                    AbsoluteAlternateUri,
                    SerializeRelationshipTarget(AbsoluteAlternateUri),
                    ExternalLinkUriRole.AbsoluteAlternate));
                relationshipIndex++;
            }
            if (RelativeAlternateUri != null)
            {
                relationships.Add(new ExternalLinkUriRelationship(
                    "rId" + relationshipIndex,
                    RelativeAlternateUri,
                    SerializeRelationshipTarget(RelativeAlternateUri),
                    ExternalLinkUriRole.RelativeAlternate));
            }
            return relationships.AsReadOnly();
        }

        internal static string SerializeRelationshipTarget(string value)
        {
            ValidateWorkbookLocation(value, null);
            string location = value.Trim();
 
            if (IsWindowsDrivePath(location))
            {
                string normalized = location.Replace('\\', '/');
                string drive = normalized.Substring(0, 2);
                string path = EscapePath(normalized.Substring(2));
                return "file:///" + drive + path;
            }
 
            if (IsUncPath(location))
            {
                string normalized = location.Replace('\\', '/').TrimStart('/');
                int separator = normalized.IndexOf('/');
                string host = normalized.Substring(0, separator);
                string path = normalized.Substring(separator);
                return "file://" + host + EscapePath(path);
            }
 
            if (IsUnixRootedPath(location))
            {
                return "file://" + EscapePath(location.Replace('\\', '/'));
            }
 
            if (Uri.TryCreate(location.Replace('\\', '/'), UriKind.Absolute, out Uri absoluteUri))
            {
                return absoluteUri.AbsoluteUri;
            }
 
            string relativeLocation = location.Replace('\\', '/');
            int query = relativeLocation.IndexOf('?');
            int fragment = relativeLocation.IndexOf('#');
            int suffix = query < 0 ? fragment : fragment < 0 ? query : Math.Min(query, fragment);
            string relativePath = suffix < 0 ? relativeLocation : relativeLocation.Substring(0, suffix);
            string relativeSuffix = suffix < 0 ? string.Empty : relativeLocation.Substring(suffix);
            return EscapePath(relativePath) + relativeSuffix;
        }

        private string GetReadableUri()
        {
            if (TargetUri != null && IsAbsoluteWorkbookLocation(TargetUri))
            {
                return TargetUri;
            }
            if (AbsoluteAlternateUri != null)
            {
                return AbsoluteAlternateUri;
            }
            if (TargetUri != null)
            {
                return TargetUri;
            }
            return RelativeAlternateUri;
        }

        private static void AddDistinctLocation(List<string> locations, string value)
        {
            if (value != null && !locations.Contains(value, StringComparer.Ordinal))
            {
                locations.Add(value);
            }
        }

        private static void ValidateWorkbookLocation(string value, bool? mustBeAbsolute)
        {
            if (string.IsNullOrWhiteSpace(value))
            {
                throw new ArgumentException("The URI cannot be null or empty.");
            }
 
            bool isAbsolute = IsAbsoluteWorkbookLocation(value.Trim());
            if (mustBeAbsolute == true && !isAbsolute)
            {
                throw new ArgumentException($"The URI must be an absolute workbook location: '{value}'.");
            }
            if (mustBeAbsolute == false && isAbsolute)
            {
                throw new ArgumentException($"The URI must be a relative workbook location: '{value}'.");
            }
 
            string path = GetLocationPath(value.Trim(), isAbsolute);
            int separator = Math.Max(path.LastIndexOf('/'), path.LastIndexOf('\\'));
            string filename = separator < 0 ? path : path.Substring(separator + 1);
            int extensionSeparator = filename.LastIndexOf('.');
            if (filename.Length == 0 || extensionSeparator <= 0 || extensionSeparator == filename.Length - 1)
            {
                throw new ArgumentException($"The URI must point to a file with an extension: '{value}'.");
            }
        }

        private static string GetLocationPath(string value, bool isAbsolute)
        {
            if (isAbsolute && !IsWindowsDrivePath(value) && !IsUncPath(value) && !IsUnixRootedPath(value)
                && Uri.TryCreate(value.Replace('\\', '/'), UriKind.Absolute, out Uri absoluteUri))
            {
                return Uri.UnescapeDataString(absoluteUri.AbsolutePath);
            }
 
            int query = value.IndexOf('?');
            int fragment = value.IndexOf('#');
            int suffix = fragment < 0 ? query < 0 ? fragment : query : query < 0 ? fragment : Math.Min(query, fragment);
            string path = suffix < 0 ? value : value.Substring(0, suffix);
            return Uri.UnescapeDataString(path);
        }

        private static string EscapePath(string path)
        {
            string[] segments = path.Split('/');
            for (int i = 0; i < segments.Length; i++)
            {
                segments[i] = Uri.EscapeDataString(Uri.UnescapeDataString(segments[i]));
            }
            return string.Join("/", segments);
        }
 

        internal void AddWorksheet(ExternalWorksheet worksheet)
        {
            if (worksheet == null)
            {
                throw new ArgumentException("The worksheet cannot be null");
            }
 
            if (worksheets.Any(item => string.Equals(item.Name, worksheet.Name, StringComparison.OrdinalIgnoreCase)))
            {
                throw new ArgumentException($"The external worksheet '{worksheet.Name}' already exists.");
            }
            worksheets.Add(worksheet);
        }

        public ExternalWorksheet GetWorksheet(string name)
        {
            ExternalWorksheet worksheet = worksheets.FirstOrDefault(item => string.Equals(item.Name, name, StringComparison.OrdinalIgnoreCase));
            if (worksheet == null)
            {
                throw new ArgumentException($"The external worksheet '{name}' does not exist.");
            }
            return worksheet;
        }

        private static bool IsAbsoluteWorkbookLocation(string value)
        {
            if (IsWindowsDrivePath(value) || IsUncPath(value) || IsUnixRootedPath(value))
            {
                return true;
            }
            return Uri.TryCreate(value, UriKind.Absolute, out Uri parsedUri) && parsedUri.IsAbsoluteUri;
        }

        private static bool IsWindowsDrivePath(string value)
        {
            return value.Length >= 3
                && char.IsLetter(value[0])
                && value[1] == ':'
                && (value[2] == '\\' || value[2] == '/');
        }

        private static bool IsUncPath(string value)
        {
            return value.StartsWith(@"\\", StringComparison.Ordinal)
                || value.StartsWith("//", StringComparison.Ordinal);
        }

        private static bool IsUnixRootedPath(string value)
        {
            return value.StartsWith("/", StringComparison.Ordinal) && !value.StartsWith("//", StringComparison.Ordinal);
        }
 
    }

    internal enum ExternalLinkUriRole
    {
        Target,
        AbsoluteAlternate,
        RelativeAlternate
    }

    internal sealed class ExternalLinkUriRelationship
    {
        public string Id { get; private set; }
        public string RawTarget { get; private set; }
        public string SerializedTarget { get; private set; }
        public ExternalLinkUriRole Role { get; private set; }
 
        public ExternalLinkUriRelationship(string id, string rawTarget, string serializedTarget, ExternalLinkUriRole role)
        {
            Id = id;
            RawTarget = rawTarget;
            SerializedTarget = serializedTarget;
            Role = role;
        }
    }
}