Fragment Extensions

// Configurable prefix for fragment queries (default: "?")
URI.fragmentPrefix: string;

/**
 * Get or set fragment prefix for this instance
 * @param value - New fragment prefix
 * @returns Current prefix or URI instance for chaining
 */
fragmentPrefix(value?: string): string | URI;

/**
 * Enhanced fragment method with query object support
 * @param value - Fragment value, true for object return, function for transform
 * @param build - Whether to rebuild URI immediately
 * @returns Fragment string, object, or URI instance for chaining
 */
fragment(value?: string | boolean | function, build?: boolean): string | object | URI;

/**
 * Add fragment query parameters
 * @param name - Parameter name or object of name-value pairs
 * @param value - Parameter value
 * @param build - Whether to rebuild URI immediately
 * @returns URI instance for chaining
 */
addFragment(name: string | object, value?: string, build?: boolean): URI;
addHash(name: string | object, value?: string, build?: boolean): URI; // Alias

/**
 * Set fragment query parameters
 * @param name - Parameter name or object of name-value pairs
 * @param value - Parameter value
 * @param build - Whether to rebuild URI immediately
 * @returns URI instance for chaining
 */
setFragment(name: string | object, value?: string, build?: boolean): URI;
setHash(name: string | object, value?: string, build?: boolean): URI; // Alias

/**
 * Remove fragment query parameters
 * @param name - Parameter name to remove
 * @param value - Specific value to remove
 * @param build - Whether to rebuild URI immediately
 * @returns URI instance for chaining
 */
removeFragment(name: string, value?: string, build?: boolean): URI;
removeHash(name: string, value?: string, build?: boolean): URI; // Alias

// Import fragment query extension
import 'urijs/src/URI.fragmentQuery';

const uri = new URI('http://example.com/page#section');

// Configure fragment prefix
uri.fragmentPrefix('?'); // Default prefix
console.log(uri.fragmentPrefix()); // '?'

// Set fragment as query-like string
uri.fragment('?name=John&age=30');
console.log(uri.fragment()); // '?name=John&age=30'

// Get fragment as object
const fragmentObj = uri.fragment(true);
console.log(fragmentObj); // { name: 'John', age: '30' }

// Add fragment parameters
uri.addFragment('city', 'NYC')
   .addFragment('country', 'USA');
console.log(uri.fragment()); // '?name=John&age=30&city=NYC&country=USA'

// Set fragment parameters (replaces existing)
uri.setFragment({
  search: 'javascript',
  category: 'programming'
});
console.log(uri.fragment()); // '?search=javascript&category=programming'

// Remove fragment parameters
uri.removeFragment('category');
console.log(uri.fragment()); // '?search=javascript'

// Transform fragment with function
uri.fragment(function(data) {
  data.timestamp = Date.now();
  return data;
});

// Custom fragment prefix
uri.fragmentPrefix('!');
uri.setFragment('page', '1');
console.log(uri.fragment()); // '!page=1'

// Configurable prefix for fragment URIs (default: "!")
URI.fragmentPrefix: string;

/**
 * Enhanced fragment method with URI object support
 * @param value - Fragment value, true for URI return, URI object to set
 * @param build - Whether to rebuild URI immediately
 * @returns Fragment string, URI instance, or this URI for chaining
 */
fragment(value?: string | boolean | URI, build?: boolean): string | URI;

/**
 * Enhanced build method with fragment URI sync
 * @param deferBuild - Don't trigger automatic rebuilding
 * @returns Complete URI string
 */
build(deferBuild?: boolean): string;

// Import fragment URI extension
import 'urijs/src/URI.fragmentURI';

const uri = new URI('http://example.com/app');

// Set fragment as URI string
uri.fragment('!/page/users?filter=active');
console.log(uri.toString()); // 'http://example.com/app#!/page/users?filter=active'

// Get fragment as URI instance
const fragmentUri = uri.fragment(true);
console.log(fragmentUri instanceof URI); // true
console.log(fragmentUri.pathname()); // '/page/users'
console.log(fragmentUri.query()); // 'filter=active'

// Manipulate fragment URI
fragmentUri.addQuery('sort', 'name')
           .pathname('/page/users/123');

// Fragment URI changes are automatically synced
console.log(uri.toString()); // 'http://example.com/app#!/page/users/123?filter=active&sort=name'

// Set fragment URI from another URI instance
const newFragmentUri = new URI('/different/path?param=value');
uri.fragment(newFragmentUri);
console.log(uri.toString()); // 'http://example.com/app#!/different/path?param=value'

// Complex fragment URI manipulation
const complexUri = new URI('http://spa.example.com/');
complexUri.fragment('!/app/dashboard');

const dashboardUri = complexUri.fragment(true);
dashboardUri.addQuery('tab', 'analytics')
            .addQuery('period', '7d')
            .fragment('chart-section');

console.log(complexUri.toString());
// 'http://spa.example.com/#!/app/dashboard?tab=analytics&period=7d#chart-section'

// Custom fragment URI prefix
complexUri.fragmentPrefix('#/');
complexUri.fragment('/router/path');
console.log(complexUri.toString()); // 'http://spa.example.com/#/router/path'

// Import both extensions
import 'urijs/src/URI.fragmentQuery';
import 'urijs/src/URI.fragmentURI';

// Start with basic URI
const appUri = new URI('http://myapp.com/');

// Use fragment as query-like for simple state
appUri.fragmentPrefix('?');
appUri.setFragment({
  modal: 'login',
  returnTo: '/dashboard'
});
console.log(appUri.toString()); // 'http://myapp.com/#?modal=login&returnTo=/dashboard'

// Switch to URI-like for complex routing
appUri.fragmentPrefix('!');
const routeUri = new URI('/app/users/123');
routeUri.addQuery('tab', 'profile');
appUri.fragment(routeUri);
console.log(appUri.toString()); // 'http://myapp.com/#!/app/users/123?tab=profile'

// Access and modify the fragment URI
const currentRoute = appUri.fragment(true);
currentRoute.segment(2, '456'); // Change user ID
currentRoute.setQuery('tab', 'settings'); // Change tab

console.log(appUri.toString()); // 'http://myapp.com/#!/app/users/456?tab=settings'

// Detect fragment type
function getFragmentType(uri) {
  const frag = uri.fragment();
  if (frag.startsWith('?')) return 'query';
  if (frag.startsWith('!')) return 'uri';
  return 'simple';
}

console.log(getFragmentType(appUri)); // 'uri'